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	"[email protected]"	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	"https://appstore.com/app"	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

{
  "customer": {
    "id": "customer_123",
    "email": "[email protected]",
    "externalId": "loyalty_customer_id",
    "balance": 500,
    "totalPoints": 1000,
    "customAttributes": {
      "third_party_id": "customer_123",
      "email": "[email protected]",
      "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

Updated 1 day ago