POST
/
headless
/
2025-06
/
{site_id}
/
customers
/
{merchant_id}
/
sessions
cURL
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": "<string>",
    "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": "<string>",
        "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": "<string>",
          "points_cost": 123
        },
        "redeemable": {
          "usage_status": "not_used",
          "kind": "<string>",
          "code_last_characters": "<string>",
          "initial_balance": {
            "amount": "<any>",
            "formatted": "<any>"
          },
          "current_balance": {
            "amount": "<any>",
            "formatted": "<any>"
          },
          "expires_at": "<string>"
        },
        "auto_refund_at": "<string>"
      }
    ],
    "available_rewards": [
      {
        "id": 123,
        "limit": {
          "count": 123,
          "interval": "day"
        },
        "kind": "<string>",
        "properties": {
          "initial_balance": {
            "amount": "<any>",
            "formatted": "<any>"
          }
        },
        "variant": {
          "tier_id": 123,
          "title": "$5 voucher",
          "enabled": true,
          "cost": {
            "kind": "<string>",
            "points": 123
          },
          "cost_text": "100 points"
        },
        "context": {
          "can_redeem": {
            "state": "<string>"
          },
          "last_claimed_at": "<string>",
          "claim_count": 123,
          "claim_limit": {
            "state": "<string>"
          }
        }
      }
    ],
    "available_rules": [
      {
        "id": 123,
        "limit": {
          "count": 123,
          "interval": "day"
        },
        "kind": "<string>",
        "variant": {
          "tier_id": 123,
          "title": "Make a purchase",
          "enabled": true,
          "result": {
            "kind": "<string>",
            "per_currency_unit": 1,
            "points": 5
          },
          "result_short_text": "5 points per $1"
        },
        "context": {
          "last_completed_at": "<string>",
          "completion_count": 123,
          "completion_limit": {
            "state": "<string>"
          }
        }
      }
    ],
    "history": [
      {
        "kind": "<string>",
        "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>",
          "handle": "<string>",
          "title": "<string>",
          "url": "<string>",
          "image_url": "<string>",
          "variant": {
            "id": "<string>",
            "title": "<string>"
          }
        },
        "quantity": 123,
        "cart_id": "<string>",
        "cart_line": {
          "kind": "<string>",
          "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": "<string>"
            },
            "minimum_line_item_quantity": {
              "state": "<string>"
            }
          }
        }
      }
    ],
    "email_marketing_consent": {
      "state": "subscribed"
    },
    "sms_marketing_consent": {
      "state": "subscribed"
    },
    "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": 50,
        "formatted": "$50"
      },
      "incentive_text": "Get a 10% discount on your order with this code when you spend over $50",
      "kind": "<string>",
      "discount_kind": "percentage",
      "discount": {
        "percentage": 10,
        "formatted": "10%"
      }
    },
    "rules": [
      {
        "id": 123,
        "limit": {
          "count": 123,
          "interval": "day"
        },
        "kind": "<string>",
        "variants": [
          {
            "tier_id": 123,
            "title": "Make a purchase",
            "enabled": true,
            "result": {
              "kind": "<string>",
              "per_currency_unit": 1,
              "points": 5
            },
            "result_short_text": "5 points per $1"
          }
        ]
      }
    ],
    "rewards": [
      {
        "id": 123,
        "limit": {
          "count": 123,
          "interval": "day"
        },
        "kind": "<string>",
        "properties": {
          "initial_balance": {
            "amount": "<any>",
            "formatted": "<any>"
          }
        },
        "variants": [
          {
            "tier_id": 123,
            "title": "$5 voucher",
            "enabled": true,
            "cost": {
              "kind": "<string>",
              "points": 123
            },
            "cost_text": "100 points"
          }
        ]
      }
    ]
  },
  "requested_cart_actions": [
    {
      "kind": "<string>",
      "reason": "redemption_expired",
      "cart_line_to_remove": {
        "kind": "<string>",
        "id": "gid://shopify/CartLine/735a73a2-666f-4df2-91dc-540bc1b8b9ba",
        "merchandise_id": "gid://shopify/ProductVariant/1001",
        "attributes": [
          {
            "key": "<string>",
            "value": "<string>"
          }
        ]
      },
      "cart_redemption": {
        "id": "A7EB"
      }
    }
  ]
}
Initialize a headless session for the customer with the given 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.
  • if no matching customer exists in LoyaltyLion for the given merchant_id, a new customer will be created, potentially enrolled into the program, and returned
  • if a matching customer is found in LoyaltyLion, they may be enrolled and returned
Customers will be enrolled based on the program’s configuration. For example, if the program is configured to auto-enroll customers, they’ll become enrolled automatically when their session is initialized. For both new and existing customers, program rules may be triggered for the customer. For example:
  • “join program” rule if the customer was just enrolled from this session
  • “pageview” rule if the channel is web and they’re viewing a relevant page
  • “download mobile app” rule if the channel is mobile

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. If a new customer is created from this API call, they'll be created in this Site, which is relevant for multi-site programs

​
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

Body

application/json

Body

​
customer
object
required

The customer involved in this session. If the customer does not yet exist in LoyaltyLion, they will be created with these properties

​
session
object

Additional information about this session, which can facilitate triggering rules, or improve program analytics

​
cart
object

If you're using cart-based rewards (like free products), you should provide a serialized version of the current customer cart here. This is used to determine which rewards are eligible for the current cart (taking cart requirements into account), and also to remove and refund any product redemptions that are no longer valid

If the current cart is empty, or does not yet exist (typical on Shopify, before the the shopper has interacted with the cart), you should pass { "kind": "empty" } to explicitly indicate an empty cart for the purposes of cart requirements

When passing a cart, check the requested_cart_actions field in the response for any actions you should perform with the cart, such as removing any reward product lines that are no longer valid An empty cart. This can be used to quickly indicate a cart that is empty or, for platforms like Shopify, used when a cart does not yet exist because the shopper has not yet added any items to it

Example:
{ "kind": "empty" }

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)

​
configuration
object
required

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

​
requested_cart_actions
Remove cart line · object[]
required

If you included a serialized cart with the request, this may contain a list of requested actions to do with the cart, such as removing any reward items that are no longer valid