curl --request POST \
--url https://api.loyaltylion.com/headless/2025-06/{site_id}/customers/{merchant_id}/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"customer": {
"email": "alice@example.com"
},
"session": {
"page_url": "https://store.example.com/products/100"
},
"cart": {
"kind": "empty"
}
}'
{
"channel": "web",
"currency": "usd",
"language": "en",
"customer": {
"state": "enrolled",
"id": 123,
"merchant_id": "<string>",
"email": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"points_approved": 123,
"points_pending": 123,
"points_spent": 123,
"enrolled_at": "<string>",
"tier_membership": {
"tier_id": 123,
"started_at": "2025-01-01T12:00:00Z",
"expires_at": "2026-01-01T12:00:00Z",
"progress": {
"kind": "points",
"valid_until": "<string>",
"points_needed_for_renewal": 123,
"upgrade_tier_id": 123,
"points_needed_for_upgrade": 123,
"tier_points": {
"now": 123,
"at_expiration": 123
}
}
},
"birthday": {
"month": 6,
"day": 25
},
"next_birthday": "2025-06-25",
"claimed_rewards": [
{
"id": 123,
"claimed_at": "<string>",
"reward_id": 123,
"title": "$5 voucher",
"state": "approved",
"source": {
"kind": "points_redemption",
"points_cost": 123
},
"redeemable": {
"usage_status": "not_used",
"kind": "gift_card",
"code_last_characters": "<string>",
"initial_balance": {
"amount": 9.9,
"formatted": "$9.90"
},
"current_balance": {
"amount": 9.9,
"formatted": "$9.90"
},
"expires_at": "<string>"
},
"auto_refund_at": "<string>"
}
],
"available_rewards": [
{
"id": 123,
"limit": {
"count": 123,
"interval": "day"
},
"kind": "gift_card",
"properties": {
"initial_balance": {
"amount": 9.9,
"formatted": "$9.90"
}
},
"variant": {
"tier_id": 123,
"title": "$5 voucher",
"enabled": true,
"cost": {
"kind": "fixed",
"points": 123
},
"cost_text": "100 points"
},
"context": {
"can_redeem": {
"state": "redeemable"
},
"last_claimed_at": "<string>",
"claim_count": 123,
"claim_limit": {
"state": "no_limit"
}
}
}
],
"available_rules": [
{
"id": 123,
"limit": {
"count": 123,
"interval": "day"
},
"kind": "birthday",
"variant": {
"tier_id": 123,
"title": "Make a purchase",
"enabled": true,
"result": {
"kind": "points",
"per_currency_unit": 1,
"points": 5
},
"result_short_text": "5 points per $1"
},
"context": {
"last_completed_at": "<string>",
"completion_count": 123,
"completion_limit": {
"state": "no_limit"
}
}
}
],
"history": [
{
"kind": "earned_points_from_rule",
"label": "Join our program",
"date": "<string>",
"points": 1,
"points_text": "500 points",
"rule": {
"id": 123,
"kind": "birthday"
},
"points_will_approve_at": "<string>",
"points_will_expire_at": "<string>",
"state": "pending"
}
],
"active_cart_redemptions": [
{
"id": "<string>",
"claimed_reward_id": 123,
"expires_at": "<string>",
"product": {
"id": "<string>",
"title": "<string>",
"url": "<string>",
"image_url": "<string>",
"variant": {
"id": "<string>",
"title": "<string>"
}
},
"quantity": 123,
"cart_id": "<string>",
"cart_line": {
"kind": "shopify",
"merchandise_id": "gid://shopify/ProductVariant/1001",
"product_id": "gid://shopify/Product/100",
"quantity": 1,
"attributes": [
{
"key": "__lion_sfp_id",
"value": "19fdf4cb"
}
]
},
"current_cart_state": {
"in_cart": true,
"cart_requirements_met": true,
"cart_requirements_detail": {
"minimum_cart_total": {
"state": "no_requirement"
},
"minimum_line_item_quantity": {
"state": "no_requirement"
}
}
}
}
],
"referral_urls": {
"direct": "<string>",
"facebook": "<string>",
"twitter": "<string>",
"email": "<string>",
"whatsapp": "<string>",
"device_share": "<string>"
}
},
"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": 9.9,
"formatted": "$9.90"
},
"incentive_text": "Get a 10% discount on your order with this code when you spend over $50",
"kind": "cart_discount_voucher",
"discount_kind": "percentage",
"discount": {
"percentage": 10,
"formatted": "10%"
}
},
"rules": [
{
"id": 123,
"limit": {
"count": 123,
"interval": "day"
},
"kind": "birthday",
"variants": [
{
"tier_id": 123,
"title": "Make a purchase",
"enabled": true,
"result": {
"kind": "points",
"per_currency_unit": 1,
"points": 5
},
"result_short_text": "5 points per $1"
}
]
}
],
"rewards": [
{
"id": 123,
"limit": {
"count": 123,
"interval": "day"
},
"kind": "gift_card",
"properties": {
"initial_balance": {
"amount": 9.9,
"formatted": "$9.90"
}
},
"variants": [
{
"tier_id": 123,
"title": "$5 voucher",
"enabled": true,
"cost": {
"kind": "fixed",
"points": 123
},
"cost_text": "100 points"
}
]
}
]
},
"requested_cart_actions": [
{
"kind": "remove_cart_line",
"reason": "redemption_expired",
"cart_line_to_remove": {
"kind": "shopify",
"id": "gid://shopify/CartLine/735a73a2-666f-4df2-91dc-540bc1b8b9ba",
"merchandise_id": "gid://shopify/ProductVariant/1001",
"attributes": [
{
"key": "<string>",
"value": "<string>"
}
]
},
"cart_redemption": {
"id": "A7EB"
}
}
]
}
curl --request POST \
--url https://api.loyaltylion.com/headless/2025-06/{site_id}/customers/{merchant_id}/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"customer": {
"email": "alice@example.com"
},
"session": {
"page_url": "https://store.example.com/products/100"
},
"cart": {
"kind": "empty"
}
}'
{
"channel": "web",
"currency": "usd",
"language": "en",
"customer": {
"state": "enrolled",
"id": 123,
"merchant_id": "<string>",
"email": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"points_approved": 123,
"points_pending": 123,
"points_spent": 123,
"enrolled_at": "<string>",
"tier_membership": {
"tier_id": 123,
"started_at": "2025-01-01T12:00:00Z",
"expires_at": "2026-01-01T12:00:00Z",
"progress": {
"kind": "points",
"valid_until": "<string>",
"points_needed_for_renewal": 123,
"upgrade_tier_id": 123,
"points_needed_for_upgrade": 123,
"tier_points": {
"now": 123,
"at_expiration": 123
}
}
},
"birthday": {
"month": 6,
"day": 25
},
"next_birthday": "2025-06-25",
"claimed_rewards": [
{
"id": 123,
"claimed_at": "<string>",
"reward_id": 123,
"title": "$5 voucher",
"state": "approved",
"source": {
"kind": "points_redemption",
"points_cost": 123
},
"redeemable": {
"usage_status": "not_used",
"kind": "gift_card",
"code_last_characters": "<string>",
"initial_balance": {
"amount": 9.9,
"formatted": "$9.90"
},
"current_balance": {
"amount": 9.9,
"formatted": "$9.90"
},
"expires_at": "<string>"
},
"auto_refund_at": "<string>"
}
],
"available_rewards": [
{
"id": 123,
"limit": {
"count": 123,
"interval": "day"
},
"kind": "gift_card",
"properties": {
"initial_balance": {
"amount": 9.9,
"formatted": "$9.90"
}
},
"variant": {
"tier_id": 123,
"title": "$5 voucher",
"enabled": true,
"cost": {
"kind": "fixed",
"points": 123
},
"cost_text": "100 points"
},
"context": {
"can_redeem": {
"state": "redeemable"
},
"last_claimed_at": "<string>",
"claim_count": 123,
"claim_limit": {
"state": "no_limit"
}
}
}
],
"available_rules": [
{
"id": 123,
"limit": {
"count": 123,
"interval": "day"
},
"kind": "birthday",
"variant": {
"tier_id": 123,
"title": "Make a purchase",
"enabled": true,
"result": {
"kind": "points",
"per_currency_unit": 1,
"points": 5
},
"result_short_text": "5 points per $1"
},
"context": {
"last_completed_at": "<string>",
"completion_count": 123,
"completion_limit": {
"state": "no_limit"
}
}
}
],
"history": [
{
"kind": "earned_points_from_rule",
"label": "Join our program",
"date": "<string>",
"points": 1,
"points_text": "500 points",
"rule": {
"id": 123,
"kind": "birthday"
},
"points_will_approve_at": "<string>",
"points_will_expire_at": "<string>",
"state": "pending"
}
],
"active_cart_redemptions": [
{
"id": "<string>",
"claimed_reward_id": 123,
"expires_at": "<string>",
"product": {
"id": "<string>",
"title": "<string>",
"url": "<string>",
"image_url": "<string>",
"variant": {
"id": "<string>",
"title": "<string>"
}
},
"quantity": 123,
"cart_id": "<string>",
"cart_line": {
"kind": "shopify",
"merchandise_id": "gid://shopify/ProductVariant/1001",
"product_id": "gid://shopify/Product/100",
"quantity": 1,
"attributes": [
{
"key": "__lion_sfp_id",
"value": "19fdf4cb"
}
]
},
"current_cart_state": {
"in_cart": true,
"cart_requirements_met": true,
"cart_requirements_detail": {
"minimum_cart_total": {
"state": "no_requirement"
},
"minimum_line_item_quantity": {
"state": "no_requirement"
}
}
}
}
],
"referral_urls": {
"direct": "<string>",
"facebook": "<string>",
"twitter": "<string>",
"email": "<string>",
"whatsapp": "<string>",
"device_share": "<string>"
}
},
"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": 9.9,
"formatted": "$9.90"
},
"incentive_text": "Get a 10% discount on your order with this code when you spend over $50",
"kind": "cart_discount_voucher",
"discount_kind": "percentage",
"discount": {
"percentage": 10,
"formatted": "10%"
}
},
"rules": [
{
"id": 123,
"limit": {
"count": 123,
"interval": "day"
},
"kind": "birthday",
"variants": [
{
"tier_id": 123,
"title": "Make a purchase",
"enabled": true,
"result": {
"kind": "points",
"per_currency_unit": 1,
"points": 5
},
"result_short_text": "5 points per $1"
}
]
}
],
"rewards": [
{
"id": 123,
"limit": {
"count": 123,
"interval": "day"
},
"kind": "gift_card",
"properties": {
"initial_balance": {
"amount": 9.9,
"formatted": "$9.90"
}
},
"variants": [
{
"tier_id": 123,
"title": "$5 voucher",
"enabled": true,
"cost": {
"kind": "fixed",
"points": 123
},
"cost_text": "100 points"
}
]
}
]
},
"requested_cart_actions": [
{
"kind": "remove_cart_line",
"reason": "redemption_expired",
"cart_line_to_remove": {
"kind": "shopify",
"id": "gid://shopify/CartLine/735a73a2-666f-4df2-91dc-540bc1b8b9ba",
"merchandise_id": "gid://shopify/ProductVariant/1001",
"attributes": [
{
"key": "<string>",
"value": "<string>"
}
]
},
"cart_redemption": {
"id": "A7EB"
}
}
]
}
merchant_id
(the
ID of the customer in your store or platform).
For convenience, the full program configuration, as returned by the Get
Configuration endpoint,
is also included in the response.
If you’re building your own headless web UI, you should generally call this once on each
page load, or, for a mobile app, once per “session”, e.g. when the customer opens or
resumes the app.
Compared to the read-only Get Customer endpoint, this endpoint can create and
enroll customers, and will trigger any relevant rules.
merchant_id
, a new
customer will be created, potentially enrolled into the program, and returnedchannel
is web
and they’re viewing a relevant pagechannel
is mobile
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
Your LoyaltyLion Site ID. If a new customer is created from this API call, they'll be created in this Site, which is relevant for multi-site programs
The sales channel from which this request is made. Must be provided as this query parameter, or the X-LoyaltyLion-Channel
header
web
, pos
, mobile
Body
The body is of type object
.
200
The response is of type object
.