Skip to main content
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

Headless API endpoints support API keys and OAuth for authentication. The legacy token & secret authentication method is not supported.
Only ever use API keys server-side. An API key is not tied to a single shopper — depending on its scopes, anyone holding it can read 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.There is no client-safe credential for the LoyaltyLion API. To build a shopper-facing UI, call the API from your own backend and expose your own authenticated endpoints to the client. To render loyalty UI directly in the browser, use the LoyaltyLion JS SDK instead.
This applies to every Headless API endpoint, including the ones that exist to power shopper-facing interfaces. Even though the Headless API is designed for building custom storefronts, mobile apps and POS interfaces, the requests themselves must be made from a server you control — not from the client rendering the UI.

​
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.

​
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.