Developer due diligence
Before committing to an implementation approach, your engineering team must review the official LoyaltyLion documentation in full and validate feasibility in a sandbox or staging environment. The examples in this guide illustrate how typical integrations work, but they do not replace technical evaluation or testing.
Each environment (POS, app, or storefront) has its own constraints, and it’s the responsibility of the implementation team to confirm that the chosen endpoints, authentication methods, and reward types work as expected for your stack.
Core principles
Shopper-facing - Headless API or, on a Shopify store, our SDK and the Loyalty Page
Backend integrations (e.g. sending order information to LoyaltyLion) - Admin API.
Use one customer ID across all channels: the customer’s ID in your store, which on Shopify is the Shopify customer ID. The Headless API calls it
merchant_id. The Admin API’s orders endpoints call itcustomer_id, because theremerchant_idis the order’s own ID.
POS Integration
Before you start, check your POS against the custom POS integration framework, which lists what a POS needs for each of these steps.
Identify customer
Initialize Session needs two things about the customer: their ID in your store, as merchant_id, and their email address. So the POS has to capture the customer’s email and look up their Shopify customer ID before it calls LoyaltyLion. If your POS’s call to Shopify doesn’t return the customer ID, change it so it does.
Initialize Session (
channel=pos) with the customer’smerchant_idand email. It finds the customer, or creates them if they are new, and returns your program’s configuration.
Authenticate the call with an API key that has the write_customers scope. The session details in the request body are optional.
Show points and rewards
The Initialize Session response carries the customer’s points_approved, their claimed_rewards (the 20 most recent) and their available_rewards. Each available reward has a can_redeem property in its context, which tells you whether this customer can claim it now, with their current points and the reward’s stock. These fields come back for enrolled customers only. A guest or blocked customer comes back with just their ID, email and name.
Claim a reward
Redeem voucher rewards with the Headless API’s redemption endpoint for that reward type, for example Cart discount voucher.
Use a reward with an order
Voucher reward - apply the returned code to the POS discount field.
Free product - free product rewards can only be redeemed into a Shopify cart, where a LoyaltyLion Shopify Function applies the discount. The redemption returns a cart line, not a SKU or a code, so a POS that doesn’t use a Shopify cart can’t offer free product rewards this way.
Do not
Don’t send the same order to LoyaltyLion twice. Orders that reach Shopify, including those from a POS that syncs to Shopify, come to us automatically, and sending them through the Admin API as well awards the points twice. Only orders that never reach Shopify go through Create Order.
Mobile App Integration
Using LoyaltyLion SDK
In order to use our SDK in your mobile app, as you would a custom site:
add the SDK snippet into the template
<head>,ensure that the snippet is initialized on each page load when needed,
authenticate the customer to display their information.
This will allow you to use our pre-made components, which may be quicker than building with the API.
Using LoyaltyLion API
Identify customer
As with SDK, ensure that any call you currently make to Shopify includes the Shopify ID of the customer so you can satisfy the required fields for the calls to LoyaltyLion.
Call Initialize Session (
channel=mobile) at least once per session, for example when the shopper first opens the app and signs in. It enrolls the shopper if your enrollment settings allow it, which also awards any Join program points. Otherwise the customer comes back as a guest.
Show points & rewards
The Initialize Session response carries the same points and rewards as for a POS, plus
available_rules, the activity rules the customer can complete. As with a POS, these come back for enrolled customers only.
Alternatively, you could use a webview session to mimic what is currently on the site.
Perform activities
For instant actions, use Complete rules – Clickthrough or the other complete-rule endpoints: Facebook like, X follow, Instagram follow, TikTok follow and custom.
Earn points on purchases
Shopify checkout - LoyaltyLion auto-receives the orders. No action needed.
Custom checkout - post with Create Order.
Send line_items with your Shopify product IDs when you create the order, so product and collection rules apply to it.
Claim & use rewards
Voucher - use Redeem reward, then apply the code at checkout.
Free product - follow the Free product reward flow.
WebViews - handle WebView JS events.
Headless Shopify Store
If you use Hydrogen, refer to our documentation and reference implementation:
For any other framework (e.g. NextJS Commerce), refer to the Hydrogen documentation above and adapt for your framework. Use the @loyaltylion/headless-api-client library, which is framework-agnostic:
Claim & use rewards
Voucher reward - use Redeem voucher.
Free product - use Free product redemption with Shopify Functions.
Shopify Theme / SDK Approach
Install and load UI
Turn on the LoyaltyLion SDK app embed, then create a Loyalty Page in LoyaltyLion and customize it in the Shopify theme editor and with CSS. For a more custom experience, embed individual SDK components and style them with CSS.
Everything else
Orders flow automatically.
The integrated Loyalty Page and Redeem Reward Modal handle rewards.
Free product rewards use Shopify Function integration.
Server responsibilities
Post orders that don’t reach Shopify with Create Order, and their refunds and cancellations with Update Order.
Post custom actions via Create Activity.
Sign customer session tokens with your SDK secret token, from Settings > General > SDK secret token. It is not the same as an API key or the older token and secret.
Commonly used webhooks
You subscribe to webhooks through the Admin API. These are the topics most integrations use:
Checklist
Surface | Must Implement | API Docs |
POS | Initialize session, redeem rewards, and create/update orders only for orders that don’t reach Shopify | |
Mobile | Initialize session, complete rules, redeem rewards | |
Headless Web | Initialize session, redeem voucher/free product | |
Shopify Theme | Install the SDK, use the Loyalty Page and modals |