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. 
