--- updatedAt: 2025-07-30T19:20:37.000Z agentTools: projectIndex: https://dev.tapcart.com/llms.txt --- # Loyalty # Loyalty Variables Loyalty variables represent loyalty program data returned from the loyalty integration. The structure includes customer information, points balance, available rewards, activities, and tier information. ## Customer Information | Property | Type | Description | Example | Availability | | :-------------------------------- | :----- | :------------------------------------------ | :----------------------------------------------- | :----------- | | `loyalty.customer.id` | String | | "123456789" | Always | | `loyalty.customer.email` | String | Customer email | "" | Always | | `loyalty.customer.externalId` | String | | "123456789" | Always | | `loyalty.customer.balance` | Number | Amount available to redeem for rewards | 500 | Always | | `loyalty.customer.totalPoints` | Number | All points earned, including redeemed ones. | 1000 | Always | | `loyalty.customer.phoneNumber` | String | | "1234567890" | If Available | | `loyalty.customer.firstName` | String | Customer first name | "John" | If Available | | `loyalty.customer.lastName` | String | Customer last name | "Doe" | If Available | | `loyalty.customer.claimedRewards` | Array | Rewards the customer has already redeemed. | `[{ "id": "123456", "code": "WELCOME10", ... }]` | If Available | ## Customer Claimed Rewards `loyalty.customer.claimedRewards[]` | `loyalty.customer.id` | String | Description | "123456789" | Always | | :-------------------- | :----- | :-------------------------------------------------------------- | :---------- | :----- | | `rewardId` | String | Reward Id | "1234" | Always | | `code` | String | Discount code | "WELCOME10" | Always | | `isUsable` | Number | `true` if the reward can still be used, `false` otherwise. | 500 | Always | | `customAttributes` | Number | `history (object)` Raw customer data from the loyalty provider. | | Always | ## Customer Custom Attributes (Provider-specific) | Property | Type | Example | Availability | | :---------------------------------- | :----- | :-------------------------------------- | :----------- | | `loyalty.customer.customAttributes` | Object | Raw customer data from Loyalty Provider | Always | ## Rewards
Property Type Example Availability
`loyalty.rewards` Array `[{ "id": "123456", ... }]` Always
`loyalty.rewards[].id` String "123456" Always
`loyalty.rewards[].description` String "50 points" Always
`loyalty.rewards[].name` String "$5 voucher" Always
`loyalty.rewards[].pointsCost` Number 50 Always
`loyalty.rewards[].type` String Provider-Specific Reward Types (e.g.): **Loyalty Lion**: `"cart_discount_voucher"`, `"product_cart"`, `"free_shipping_voucher"`... **Yotpo**: `"product"`, `"product_variable"`... Always
`loyalty.rewards[].isAvailable` Boolean true Always
## Rewards Custom Attributes (Provider-specific) | Property | Type | Example | Availability | | :--------------------------------- | :----- | :------------------------------------ | :----------- | | `loyalty.rewards.customAttributes` | Object | Raw reward data from Loyalty Provider | Always | ## History | Property | Type | Example | Availability | | :------------------------------ | :----- | :------------------------------- | :----------- | | `loyalty.history` | Array | `[{ "title": "Purchase", ... }]` | If Available | | `loyalty.history[].title` | String | "Purchase" | Always | | `loyalty.history[].createdAt` | Date | "2024-01-15T10:30:00Z" | Always | | `loyalty.history[].completedAt` | Date | "2024-01-15T10:30:00Z" | Always | | `loyalty.history[].points` | Number | 100 | Alway | ## Activities | Property | Type | Example | Availability | | :---------------------------------------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------- | :----------- | | `loyalty.activities` | Array | `[{ "id": "123456", ... }]` | Always | | `loyalty.activities[].id` | String | "123456" | Always | | `loyalty.activities[].type` | String | "purchase" \| "join\_program" \| "pageview" \| "custom" \| "instagram\_follow" \| "facebook\_like" \| "birthday" \| "referral | Always | | `loyalty.activities[].customerId` | String | "customer\_123" | Always | | `loyalty.activities[].action_name` | String | "download\_the\_app" | Always | | `loyalty.activities[].title` | String | "Download the App" | Always | | `loyalty.activities[].details` | String | "100 points" | Always | | `loyalty.activities[].reward_text` | String | "100 points" | Always | | `loyalty.activities[].cta_text` | String | "Download the App" | Always | | `loyalty.activities[].icon` | String | "mobile" | Always | | `loyalty.activities[].url` | String | "" | If Available | | `loyalty.activities[].max_completions_per_user` | Number | 1 | Always | | `loyalty.activities[].min_actions_required` | Number | 1 | Always | ## Activity Status `loyalty.activities[].status` | Property | Type | Description | Example | Availability | | :--------------------------------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------- | :------ | :----------- | | `customer_actions_completed` | Number | Number of actions the customer has completed toward a multi-step campaign. Only applies to campaigns with more than one step. | 1 | Always | | `customer_minutes_until_next_action` | Number | How long (in minutes) the customer must wait before they can take the next eligible action. | 0 | Always | | `customer_minutes_until_next_completion` | Number | How long (in minutes) the customer must wait before they can complete the campaign again. | 0 | Always | | `customer_times_completed` | Number | Number of times the customer has fully completed a campaign and earned the reward. A value of 1 means it was completed once. | 1 | Always | | `global_completions_left` | Number | Number of completions remaining for the campaign globally (if there's a limit for all users). | 0 | Always | ## Activities Custom Attributes (Provider-specific) | Property | Type | Example | Availability | | :------------------------------------ | :----- | :-------------------------------------- | :----------- | | `loyalty.activities.customAttributes` | Object | Raw activity data from Loyalty Provider | Always | ## Tiers | Property | Type | Example | Availability | | :------------------------- | :------ | :-------------------------------------- | :----------- | | `loyalty.tiers` | Array | `[{ "id": "12345", ... }]` | Always | | `loyalty.tiers[].id` | String | "12345" | Always | | `loyalty.tiers[].name` | String | "Bronze" | Always | | `loyalty.tiers[].level` | Number | 1 | Always | | `loyalty.tiers[].isActive` | Boolean | false | Always | | `loyalty.tiers[].benefits` | Array | `["Free Shipping", "Priority Support"]` | Always | ## Tier Requirements | Property | Type | Example | Availability | | :----------------------------------------- | :----- | :---------------------------- | :----------- | | `loyalty.tiers[].requirements` | Array | `[{ "type": "points", ... }]` | Always | | `loyalty.tiers[].requirements[].type` | String | "points" | Always | | `loyalty.tiers[].requirements[].threshold` | Number | 0 | Always | | `loyalty.tiers[].requirements[].progress` | Number | 100 | Always | ## Sample Loyalty Response ```json { "customer": { "id": "customer_123", "email": "customer@example.com", "externalId": "loyalty_customer_id", "balance": 500, "totalPoints": 1000, "customAttributes": { "third_party_id": "customer_123", "email": "customer@example.com", "first_name": "John", "last_name": "Doe", "phone_number": "+1234567890", "points_balance": 500, "points_earned": 1000, "vip_tier_name": "Gold", "vip_tier_actions_completed": { "points_earned": 750 }, "amount_spent_cents_in_customer_currency": 50000, "purchases_made": 3, "referrals_completed": 1, "history_items": [ { "action": "Purchase", "created_at": "2024-01-15T10:30:00Z", "completed_at": "2024-01-15T10:30:00Z", "points": 100, "redemption_option_id": null, "status": "Completed" } ] } }, "history": [ { "title": "Purchase", "createdAt": "2024-01-15T10:30:00Z", "completedAt": "2024-01-15T10:30:00Z", "points": 100, "customAttributes": { "action": "Purchase", "created_at": "2024-01-15T10:30:00Z", "completed_at": "2024-01-15T10:30:00Z", "points": 100 } } ], "rewards": [ { "id": "reward_789", "name": "$10 Off Purchase", "description": "Get $10 off your next purchase", "pointsCost": 1000, "type": "discount", "isAvailable": false, "customAttributes": { "id": "reward_789", "name": "$10 Off Purchase", "description": "Get $10 off your next purchase", "amount": 1000, "discount_type": "discount", "variant_id": null } } ], "activities": [ { "id": "activity_123", "type": "CustomAction", "customerId": "customer_123", "display_order": "1", "action_name": "download_the_app", "max_completions_per_user": 1, "min_actions_required": 1, "status": { "customer_actions_completed": 1, "customer_minutes_until_next_action": null, "customer_minutes_until_next_completion": null, "customer_times_completed": 1, "global_completions_left": 999 }, "createdAt": "2024-01-01T00:00:00Z", "title": "Download Our App", "details": "Download our mobile app to earn points", "reward_text": "Earn 50 points", "cta_text": "Download Now", "icon": "mobile", "url": "https://appstore.com/app", "customAttributes": {} } ], "tiers": [ { "id": "tier_1", "name": "Bronze", "level": 1, "requirements": [ { "type": "points", "threshold": 0, "progress": 500 }, { "type": "orders", "threshold": 1, "progress": 3 } ], "benefits": ["Free Shipping", "Priority Support"], "isActive": false, "customAttributes": {} }, { "id": "tier_2", "name": "Gold", "level": 2, "requirements": [ { "type": "points", "threshold": 1000, "progress": 500 }, { "type": "amountSpent", "threshold": 10000, "progress": 50000 } ], "benefits": ["Free Shipping", "Priority Support", "Exclusive Discounts"], "isActive": true, "customAttributes": {} } ] } ``` > ⚠️ Important Notes > > * The loyalty data is automatically populated when a customer accesses the app when logged in > * The activity with action\_name "download\_the\_app" is automatically recorded when the customer uses the mobile app > * The activity with action\_name "enable\_push\_notifications" will initiate request for the customer to enable push notifications when selected in the mobile app > * All custom attributes contain provider-specific data that may vary based on your loyalty program configuration > * Points balance and rewards availability are calculated in real-time based on the customer's current status > * Tier requirements include different types: "points", "orders", "referrals", and "amountSpent" > * Some features may not be supported depending on Loyalty Providers which include: > * Yotpo > * Loyalty Lion > * Smile > * Rivo