Skip to main content
GET
/
headless
/
2025-06
/
{site_id}
/
customers
/
{merchant_id}
cURL
curl --request GET \
  --url https://api.loyaltylion.com/headless/2025-06/{site_id}/customers/{merchant_id} \
  --header 'Authorization: Bearer <token>'
{
  "channel": "web",
  "currency": "usd",
  "language": "en",
  "customer": {
    "state": "enrolled",
    "id": 1,
    "merchant_id": "1001",
    "email": "alice@example.com",
    "first_name": "Alice",
    "last_name": "Kyako",
    "points_approved": 500,
    "points_pending": 200,
    "points_spent": 500,
    "enrolled_at": "2025-06-01T15:00:00Z",
    "tier_membership": {
      "tier_id": 1,
      "started_at": "2025-06-01T15:00:00Z",
      "expires_at": "2026-06-01T15:00:00Z",
      "progress": {
        "kind": "spend",
        "tier_spend": {
          "now": {
            "amount": 200,
            "formatted": "$200"
          },
          "at_expiration": {
            "amount": 100,
            "formatted": "$100"
          }
        },
        "valid_until": "2026-06-01T15:00:00Z",
        "upgrade_tier_id": 2,
        "spend_needed_for_renewal": null,
        "spend_needed_for_upgrade": {
          "amount": 800,
          "formatted": "$800"
        }
      }
    },
    "birthday": {
      "day": 22,
      "month": 6
    },
    "next_birthday": "2026-06-22",
    "claimed_rewards": [
      {
        "id": 1,
        "claimed_at": "2025-06-03T00:00:00Z",
        "auto_refund_at": null,
        "reward_id": 1,
        "title": "$5 discount",
        "state": "approved",
        "source": {
          "kind": "points_redemption",
          "points_cost": 500
        },
        "redeemable": {
          "kind": "cart_discount_voucher",
          "applies_to_order_type": "all",
          "recurring_cycle_limit": 1,
          "code": "LL-XAIA8471",
          "discount_type": "fixed",
          "discount": {
            "amount": 5,
            "formatted": "$5"
          },
          "minimum_spend": {
            "amount": 50,
            "formatted": "$50"
          },
          "expires_at": "2026-06-03T00:00:00Z",
          "used_at": null,
          "usage_status": "not_used"
        }
      }
    ],
    "available_rules": [
      {
        "id": 1,
        "kind": "pageview",
        "limit": {
          "count": 5,
          "interval": "day"
        },
        "variant": {
          "tier_id": 1,
          "enabled": true,
          "title": "Visit our online store",
          "result": {
            "kind": "points",
            "per_currency_unit": null,
            "points": 10
          },
          "result_short_text": "10 points"
        },
        "context": {
          "last_completed_at": "2025-06-10T05:08:37.582Z",
          "completion_count": 22,
          "completion_limit": {
            "state": "limit_not_reached",
            "interval": "day",
            "allowed_completions_within_interval": 5,
            "completion_count_within_interval": 3,
            "remaining_completions_within_interval": 2
          }
        }
      },
      {
        "id": 2,
        "kind": "join_program",
        "limit": {
          "count": 1,
          "interval": null
        },
        "variant": {
          "tier_id": 1,
          "enabled": true,
          "title": "Join our loyalty program",
          "result": {
            "kind": "points",
            "per_currency_unit": null,
            "points": 100
          },
          "result_short_text": "100 points"
        },
        "context": {
          "last_completed_at": "2025-06-10T07:44:24.537Z",
          "completion_count": 1,
          "completion_limit": {
            "state": "limit_reached_forever"
          }
        }
      },
      {
        "id": 3,
        "kind": "purchase",
        "limit": null,
        "variant": {
          "tier_id": 1,
          "enabled": true,
          "title": "Make a purchase",
          "result": {
            "kind": "points",
            "per_currency_unit": 1,
            "points": 5
          },
          "result_short_text": "5 points per $1"
        },
        "context": {
          "last_completed_at": "2025-06-10T05:08:37.582Z",
          "completion_count": 3,
          "completion_limit": {
            "state": "no_limit"
          }
        }
      }
    ],
    "available_rewards": [
      {
        "id": 1,
        "kind": "cart_discount_voucher",
        "limit": null,
        "properties": {
          "discount_type": "fixed",
          "discount": {
            "amount": 5,
            "formatted": "$5"
          },
          "applies_to_order_type": "one_time",
          "recurring_cycle_limit": 1,
          "minimum_spend": {
            "amount": 10,
            "formatted": "$10"
          }
        },
        "variant": {
          "tier_id": 1,
          "enabled": true,
          "title": "$5 discount",
          "cost": {
            "kind": "fixed",
            "points": 500
          },
          "cost_text": "500 points"
        },
        "context": {
          "can_redeem": {
            "state": "redeemable"
          },
          "last_claimed_at": "2025-06-03T00:00:00Z",
          "claim_count": 1,
          "claim_limit": {
            "state": "no_limit"
          }
        }
      },
      {
        "id": 2,
        "kind": "cart_discount_voucher",
        "limit": null,
        "properties": {
          "discount_type": "percentage",
          "discount": {
            "percentage": 10,
            "formatted": "10%"
          },
          "applies_to_order_type": "one_time",
          "recurring_cycle_limit": 1,
          "minimum_spend": {
            "amount": 50,
            "formatted": "$50"
          }
        },
        "variant": {
          "tier_id": 1,
          "enabled": true,
          "title": "10% discount",
          "cost": {
            "kind": "fixed",
            "points": 1000
          },
          "cost_text": "1,000 points"
        },
        "context": {
          "can_redeem": {
            "state": "insufficient_points",
            "additional_points_required": 500
          },
          "last_claimed_at": null,
          "claim_count": 0,
          "claim_limit": {
            "state": "no_limit"
          }
        }
      }
    ],
    "history": [
      {
        "kind": "redeemed_points_for_reward",
        "label": "$5 discount",
        "date": "2025-06-03T15:00:00Z",
        "points": -500,
        "points_text": "-500 points",
        "reward": {
          "id": 1,
          "kind": "cart_discount_voucher"
        },
        "claimed_reward_id": 1,
        "state": "approved"
      },
      {
        "kind": "entered_tier",
        "label": "Entered Silver tier",
        "date": "2025-06-02T15:00:00Z",
        "tier": {
          "id": 1,
          "name": "Silver"
        }
      },
      {
        "kind": "earned_points_from_rule",
        "label": "Joined program",
        "date": "2025-06-01T15:00:00Z",
        "points": 500,
        "points_text": "500 points",
        "points_will_approve_at": null,
        "points_will_expire_at": "2026-06-01T00:00:00Z",
        "state": "approved",
        "rule": {
          "id": 1,
          "kind": "join_program"
        }
      }
    ],
    "active_cart_redemptions": [],
    "email_marketing_consent": {
      "state": "subscribed"
    },
    "sms_marketing_consent": {
      "state": "not_subscribed"
    },
    "referral_urls": {
      "email": "https://prz.io/_",
      "direct": "https://prz.io/_",
      "facebook": "https://prz.io/_",
      "twitter": "https://prz.io/_",
      "whatsapp": "https://prz.io/_",
      "device_share": "https://prz.io/_"
    }
  },
  "configuration": {
    "channel": "web",
    "currency": "usd",
    "language": "en",
    "program": {
      "name": "Lion Rewards"
    },
    "tier_configuration": {
      "boundary_mode": "spend",
      "tiers": [
        {
          "id": 1,
          "name": "Silver",
          "benefit_ids": [
            1
          ],
          "hidden": false,
          "kind": "spend",
          "position": 1,
          "lower_bound": {
            "amount": 0,
            "formatted": "$0"
          },
          "upper_bound": {
            "amount": 99.99,
            "formatted": "$99.99"
          }
        },
        {
          "id": 2,
          "name": "Gold",
          "benefit_ids": [
            1,
            2
          ],
          "hidden": false,
          "kind": "spend",
          "position": 2,
          "lower_bound": {
            "amount": 100,
            "formatted": "$100"
          },
          "upper_bound": null
        }
      ],
      "tier_benefits": [
        {
          "id": 1,
          "label": "Early access to new products",
          "secret": false,
          "details": null
        },
        {
          "id": 2,
          "label": "Free makeup classes",
          "secret": false,
          "details": {
            "plaintext": "Email classes@example.com to sign up to a class\n",
            "html": "<p>Email classes@example.com to sign up to a class</p>"
          }
        }
      ],
      "membership": {
        "mode": "rolling",
        "duration_months": 12
      }
    },
    "referee_incentive": {
      "minimum_spend": {
        "amount": 100,
        "formatted": "$100"
      },
      "incentive_text": "Get a 10% discount on your order with this code when you spend over $100",
      "kind": "cart_discount_voucher",
      "discount_kind": "percentage",
      "discount": {
        "percentage": 10,
        "formatted": "10%"
      }
    },
    "rules": [
      {
        "id": 1,
        "kind": "purchase",
        "variants": [
          {
            "tier_id": 1,
            "enabled": true,
            "title": "Make a purchase",
            "result": {
              "kind": "points",
              "per_currency_unit": 1,
              "points": 5
            },
            "result_short_text": "5 points per $1"
          },
          {
            "tier_id": 2,
            "enabled": true,
            "title": "Make a purchase",
            "result": {
              "kind": "points",
              "per_currency_unit": 1,
              "points": 10
            },
            "result_short_text": "10 points per $1"
          }
        ],
        "limit": null
      },
      {
        "id": 2,
        "kind": "pageview",
        "variants": [
          {
            "tier_id": 1,
            "enabled": true,
            "title": "Visit our online store",
            "result": {
              "kind": "points",
              "per_currency_unit": null,
              "points": 100
            },
            "result_short_text": "100 points"
          },
          {
            "tier_id": 2,
            "enabled": true,
            "title": "Visit our online store",
            "result": {
              "kind": "points",
              "per_currency_unit": null,
              "points": 200
            },
            "result_short_text": "200 points"
          }
        ],
        "limit": {
          "count": 1,
          "interval": "week"
        }
      }
    ],
    "rewards": [
      {
        "id": 1,
        "kind": "cart_discount_voucher",
        "properties": {
          "discount_type": "fixed",
          "discount": {
            "amount": 5,
            "formatted": "$5"
          },
          "applies_to_order_type": "one_time",
          "recurring_cycle_limit": 1,
          "minimum_spend": {
            "amount": 10,
            "formatted": "$10"
          }
        },
        "variants": [
          {
            "tier_id": 1,
            "enabled": true,
            "title": "$5 discount",
            "cost": {
              "kind": "fixed",
              "points": 500
            },
            "cost_text": "500 points"
          },
          {
            "tier_id": 2,
            "enabled": true,
            "title": "$5 discount",
            "cost": {
              "kind": "fixed",
              "points": 400
            },
            "cost_text": "400 points"
          }
        ],
        "limit": null
      },
      {
        "id": 2,
        "kind": "cart_variable_discount_voucher",
        "properties": {
          "minimum_discount": {
            "amount": 1,
            "formatted": "$1"
          },
          "maximum_discount": {
            "amount": 100,
            "formatted": "$100"
          },
          "applies_to_order_type": "all",
          "minimum_spend_before_discount": null,
          "minimum_spend_after_discount": null
        },
        "variants": [
          {
            "tier_id": 1,
            "enabled": false,
            "title": "Redeem points at checkout",
            "cost": {
              "kind": "variable",
              "unit": "discount_amount",
              "points_per_unit": 100
            },
            "cost_text": "100 points per $1"
          },
          {
            "tier_id": 2,
            "enabled": true,
            "title": "Redeem points at checkout",
            "cost": {
              "kind": "variable",
              "unit": "discount_amount",
              "points_per_unit": 100
            },
            "cost_text": "100 points per $1"
          }
        ],
        "limit": null
      }
    ]
  }
}
Retrieve a customer by merchant_id (the ID of the customer in your store or platform). If no matching customer exists, a 404 response will be returned. For convenience, the full program configuration, as returned by the Get Configuration endpoint, is also included in the response. Compared to the Initialize Session endpoint, this endpoint is readonly and will never create or update a customer, or trigger any rules. This endpoint is useful when you know the customer will already exist, and just want to retrieve their information quickly. For example, if the customer session is initialized elsewhere (either by you, or the main LoyaltyLion SDK).

Authorizations

​
Authorization
string
header
required

An API key linked to a Program in LoyaltyLion, with a set of permissions (scopes). API keys can be created manually, or acquired through an OAuth2 flow. The API key should be provided as a Bearer token in the Authorization header

Path Parameters

​
site_id
number
required

Your LoyaltyLion Site ID

​
merchant_id
string
required

The ID of the customer in your platform or ecommerce store.

For Shopify stores, you can pass either a GID or a regular numeric ID. If you do pass a GID you must encode it as a URL parameter, e.g. gid%3A%2F%2Fshopify%2FCustomer%2F1001

Minimum length: 1

Query Parameters

​
channel
enum<string>

The sales channel from which this request is made. Must be provided as this query parameter, or the X-LoyaltyLion-Channel header

Available options:
web,
pos,
mobile

Response

200

​
channel
enum<string>
required

The sales channel for which this response was generated

Available options:
web,
pos,
mobile
​
currency
string
required

ISO 4217 code indicating the currency for any financial values in this response

Example:

"usd"

​
language
enum<string>
required

ISO 639-1 code indicating the language used for any text in this response

Available options:
en,
de,
es,
fr,
it,
nl,
sv
​
customer
object
required

The customer matched by merchant_id. The customer's state property indicates if the customer is a member of the program (enrolled), not a member (guest), or has been blocked from the program (blocked)

  • Enrolled customer
  • Guest customer
  • Blocked customer
​
configuration
object
required

The complete program configuration. This is the same configuration that is returned by the Get Configuration endpoint

⌘I