> ## 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.
# Referrals
**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](/sdk/overview) instead.
The Headless API supports the full referral loop: your shoppers share their
personal referral links, their friends claim the referral incentive and buy
with it, and the referrer is rewarded automatically. This guide walks through
the loop end to end for a headless storefront or mobile app.
If you haven't read it yet, the [Referrals feature
overview](/docs/features/referrals) explains how referrals work in general —
this guide covers the headless-specific parts.
## How the loop fits together
1. An enrolled customer has a set of personal referral links, one per share
channel
2. They share one. You [record the share](#track-shares) so it appears in
referral analytics
3. Their friend opens the link, which redirects to your store with an
`ll_ref_id` parameter
4. You exchange that `ll_ref_id` for a discount code using the [Claim Referee
Incentive](/headless-api/2025-06/referrals/claim-referee-incentive) endpoint,
and show the code to the friend
5. The friend places their first order using the code. Once that order reaches
LoyaltyLion — through your platform integration, or the [Orders
API](/api-reference/v2/resources/orders/create-order) on custom platforms —
the two customers are linked and the referrer is rewarded, with no further
referral-specific calls
## Get a customer's referral links
An enrolled customer's links are on the `customer` object returned by [Get
Customer](/headless-api/2025-06/customers/get-customer) and [Initialize
Session](/headless-api/2025-06/customers/initialize-session), under
`referral_urls`. There's one URL per channel — `direct`, `facebook`,
`twitter`, `email`, `whatsapp`, `instagram` and `device_share` — and they all
point to the same place; the channel only affects how the referral is
categorized in analytics.
Use `device_share` for a native share sheet in a mobile app, and `direct`
anywhere you're unsure.
`referral_urls` is `null` when referrals aren't enabled for your program.
## Handle the inbound referral link
Referral links are permanent redirects. When a shopper opens one, we record
the visit and redirect them to your storefront with the referral id appended:
```
https://store.example.com/?ll_ref_id=jRq0X
```
Capture the `ll_ref_id` value from the URL and hold onto it (for example in
the session) — it's the input to the claim endpoint below.
**Mobile apps and deep links:** if your app uses deep links, the OS may open
your app instead of the browser when the shopper taps a referral link. This is
fine — the redirect that carries `ll_ref_id` happens before the OS hands over
to your app, so the visit is already tracked. Your app just needs to read
`ll_ref_id` from the URL it was opened with.
## Claim the referee incentive
On a storefront running the LoyaltyLion SDK, arriving with an `ll_ref_id`
triggers a welcome modal offering the friend a discount code. Headless, you build that experience yourself with the
[Claim Referee Incentive](/headless-api/2025-06/referrals/claim-referee-incentive)
endpoint: send the `referral_id`, get back a voucher code to display.
A few things to know:
* **Send the shopper's IP address, not your server's.** The `ip_address` field
is required and is used for referral fraud detection. Forward the address
your server received the shopper's request from
* **`user_agent` is also required.** Forward the shopper's user agent string;
where there genuinely isn't one — such as a native mobile app — send `null`
explicitly
* **Send `referee_email` whenever you know it.** It binds the voucher to that
shopper and lets us reject self-referrals and referrals of existing
members. Without an email, those checks can't run
* **Handle `referee_email_required`.** When the referrer isn't an enrolled
member (a guest who signed up just to share a link), the claim is rejected
with this error code until you supply the friend's email — collect it and
retry
* **Retries are safe.** Claiming again with the same inputs returns the same
code
* To describe the offer ("Get 10% off your first order"), use
`referee_incentive` from the
[configuration](/headless-api/2025-06/configuration/get-configuration) —
it includes localized `incentive_text`, and details like the discount, any
minimum spend, and any maximum discount. When the offer is limited to a
collection, `collection_restriction_text` carries the merchant's description
of that restriction — it isn't part of `incentive_text`, so display it
alongside
## Track shares
When a shopper shares their link, record it with [Track
Share](/headless-api/2025-06/referrals/track-share) — pass the customer and
the channel they shared on. This is what populates the share counts in your
referral analytics; without it, your dashboard will show referral visits and
purchases but no shares.
## Attribution: how the referral completes
You don't need to do anything special at checkout. When the friend's order is
processed — including orders submitted through the [Orders
API](/api-reference/v2/resources/orders/create-order) — LoyaltyLion matches
the referral voucher code on the order, links the friend to their referrer,
and triggers your referral rule.
If the friend didn't use the voucher, you can still attribute the referral
explicitly by passing the `ll_ref_id` value as `referral_id` on the [Create
Order](/api-reference/v2/resources/orders/create-order) request, or on a
`$signup` activity via [Create
Activity](/api-reference/v2/resources/activities/create-activity).
Referrals only complete on the friend's **first** order. If you import a
customer's historical orders, do so before relying on referral attribution — a
referred customer who already has other orders on record won't trigger the
referral reward.
## Custom platform stores: import voucher codes first
On platforms with a discount API — Shopify, BigCommerce, Adobe Commerce —
referral voucher codes are created on demand. On custom platform stores,
LoyaltyLion issues codes from a pool you import in advance — so referrals
won't work until codes have been uploaded, and the claim endpoint returns a
`no_vouchers_available` error if the pool runs dry. Keep it topped up.