Skip to main content
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.
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 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 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 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 on custom platforms — the two customers are linked and the referrer is rewarded, with no further referral-specific calls
An enrolled customer’s links are on the customer object returned by Get Customer and 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. 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:
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 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 — 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 — 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 — 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 request, or on a $signup activity via 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.