Skip to main content
The Headless API is included in the Classic plan and above. On a lower plan, contact your LoyaltyLion account manager or our support team to have it enabled as an add-on.
The LoyaltyLion Headless API can be used to build headless integrations. For example, it can be used to:
  • build a custom UI for a headless ecommerce storefront, e.g. Shopify Hydrogen
  • incorporate your loyalty program into a mobile app, using native UI components, or a custom POS system
You can use Headless API endpoints to:
  • retrieve program configuration, including rules, rewards, and tiers
  • find, create, and enroll customers
  • redeem rewards and trigger rules for customers

​
Authentication

The Headless API has two authentication flows. A storefront that proxies every call through its own backend needs only the first; one that calls the API from the client uses the second, usually alongside the first.

​
Server-side flow

Every Headless API endpoint can be called from a server you control, using an API key or an OAuth access token. The legacy token & secret authentication method is not supported.
Only ever use API keys server-side. Depending on its permissions, anyone holding it can read all your customers’ data and redeem rewards on their behalf. Never send an API key to a browser, bundle it into a mobile app, or embed it in a POS client. If it has been exposed, disable and rotate it immediately.

​
Client-side flow

Requests made directly from a browser, mobile app or other client-owned device authenticate with a customer session token: a credential scoped to a single site and customer, which most shopper-facing endpoints accept in place of an API key. You sign it yourself with your site’s SDK token, on your backend or in Liquid on a Shopify theme, with no LoyaltyLion API call involved.

​
Required request parameters

Headless API endpoints require a site_id property in the path, and a channel property passed as a query parameter or header.

​
Site ID

All Headless API endpoints require a site_id in the path, e.g. GET /headless/2025-06/{site_id}/configuration. This is the ID of your site in LoyaltyLion. You can find it by signing into LoyaltyLion - it’s the number after the /sites/ part of the URL, e.g. /sites/123. If you have a multi-site program, you can use any of the site IDs within the program to interact with the Headless API. The exception is a customer session token, which only works with the site ID it was signed for.

​
Channel

Program configuration can vary based on the current channel, which will be one of pos (point of sale), web (online storefront), and mobile (mobile app). For example, rewards can be configured to only work on POS, in which case those rewards won’t be included in the responses for any API calls where channel=web. The value of this parameter should match the platform in which you’re using the Headless API. For example, if you’re using the API inside a native mobile app, you should set the channel to mobile. To pass this parameter as a HTTP header, use X-LoyaltyLion-Channel.

​
Optional request parameters

Headless API endpoints also support a language query parameter or header, which, in combination with a multi-language site, specifies which language text should be returned in.

​
Language

By default, all text in Headless API responses will be returned in the associated site’s default language. If you are using multi-language, you can specify the desired language when making the request. This can passed as the language query parameter, or as the X-LoyaltyLion-Language header. The value of the parameter/header must match the language code of a configured language, such as en-gb or ja. Unrecognized language codes will be ignored, and the default language will be used instead.