Customer object - Mage Loyalty Documentation

The customer object represents a member of your loyalty program. Customers are identified by their Shopify customer ID or email address.

Attributes

Field	Type	Description
`shopify_customer_id`	string	The customer’s Shopify customer ID
`email`	string	Email address
`first_name`	string	First name
`last_name`	string	Last name
`current_points`	integer	Current available points balance. Minor currency units in store-credit mode (see Loyalty modes)
`lifetime_points`	integer	Total points earned over the lifetime of the account
`redeemed_points`	integer	Total points spent on rewards
`loyalty_status`	string	Either `member` or `excluded`
`loyalty_mode`	string	Either `points` or `store_credit`
`store_credit`	object \| null	Pre-converted balance in store-credit mode, or `null` in points mode (see below)
`date_of_birth`	string \| null	ISO 8601 date, or `null` if not set
`referral_url`	string \| null	The customer’s unique referral link, or `null` if not generated
`referral_code`	string \| null	The customer’s referral code, or `null` if not generated
`vip_tier`	object \| null	The customer’s current VIP tier (see below)
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Embedded VIP tier

When present, the vip_tier object contains:

Field	Type	Description
`id`	string	Tier ID
`name`	string	Tier name
`threshold`	integer	Lifetime points required to reach this tier
`points_multiplier`	number	Points earning multiplier for this tier
`badge_image_url`	string \| null	URL to the tier badge image
`badge_color`	string \| null	Hex color code for the tier badge

Store credit

On store-credit shops, store_credit holds the balance pre-converted to money so you do not have to do the minor-unit math. It is null in points mode. See Loyalty modes.

Field	Type	Description
`balance_minor`	integer	The balance in minor units (identical to `current_points`)
`balance`	string	The balance in major units as a decimal string, for example `"4.50"`
`balance_formatted`	string	A localized display string, for example `"£4.50"`
`currency`	string	The ISO 4217 currency code

Example

{
  "type": "customer",
  "id": "6789012345",
  "attributes": {
    "shopify_customer_id": "6789012345",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "current_points": 450,
    "lifetime_points": 1200,
    "redeemed_points": 750,
    "loyalty_status": "member",
    "loyalty_mode": "points",
    "store_credit": null,
    "date_of_birth": "1990-05-15T00:00:00.000Z",
    "referral_url": "https://mystore.myshopify.com?referral_code=ABC123",
    "referral_code": "ABC123",
    "vip_tier": {
      "id": "tier_abc",
      "name": "Gold",
      "threshold": 500,
      "points_multiplier": 1.5,
      "badge_image_url": null,
      "badge_color": "#FFD700"
    },
    "created_at": "2024-01-15T10:00:00.000Z",
    "updated_at": "2024-06-20T14:30:00.000Z"
  }
}

Example (store-credit shop)

On a store-credit shop the points fields are minor units, loyalty_mode is store_credit, and store_credit is populated:

{
  "type": "customer",
  "id": "6789012345",
  "attributes": {
    "shopify_customer_id": "6789012345",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "current_points": 450,
    "lifetime_points": 1200,
    "redeemed_points": 750,
    "loyalty_status": "member",
    "loyalty_mode": "store_credit",
    "store_credit": {
      "balance_minor": 450,
      "balance": "4.50",
      "balance_formatted": "£4.50",
      "currency": "GBP"
    },
    "date_of_birth": "1990-05-15T00:00:00.000Z",
    "referral_url": "https://mystore.myshopify.com?referral_code=ABC123",
    "referral_code": "ABC123",
    "vip_tier": {
      "id": "tier_abc",
      "name": "Gold",
      "threshold": 500,
      "points_multiplier": 1.5,
      "badge_image_url": null,
      "badge_color": "#FFD700"
    },
    "created_at": "2024-01-15T10:00:00.000Z",
    "updated_at": "2024-06-20T14:30:00.000Z"
  }
}