> ## Documentation Index
> Fetch the complete documentation index at: https://developers.loyaltylion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

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](/api-reference/authentication/api-keys) or an [OAuth access
token](/api-reference/authentication/oauth). The legacy token & secret
authentication method is not supported.

<Warning>
  **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.
</Warning>

### Client-side flow

Requests made directly from a browser, mobile app or other client-owned device
authenticate with a [customer session token](/headless-api/session-tokens): 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](https://app.loyaltylion.com/login) - 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](/headless-api/session-tokens), 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.