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 function as expected for your stack.
Core principles
Shopper-facing - Headless API or standard Shopify via our SDK + Integrated Loyalty Page
Backend integrations (e.g. sending order information to LoyaltyLion) - Admin API.
Use one customer ID (
merchant_id) across all channels.
POS Integration
Identify customer
It is required for the POS user to add the email address (or current identifier used) to the POS terminal to fetch the Shopify data. Assuming this will bring over the Shopify ID of the customer, this will satisfy the following call.
If not, you will need to change the call to Shopify to ensure the merchant_id is part of the initial response.
Initialize Session (
channel=pos) with yourmerchant_id- Creates or finds the customer, and returns the program config.
Must also pass the session
Show points and rewards
In the above response, we will show the points_approved, any claimed rewards and available_rewards - examine the can_redeem property to know which rewards can be claimed by a customer with their current points, which rewards are in stock, etc.
Claim a reward
Redeem reward via Headless API for free product or voucher types.
Use a reward with an order
Voucher reward - apply the returned code to the POS discount field.
Free product - add the returned SKU as a zero-priced line.
Do not
Don’t “award” purchase points from the POS UI; orders must go through Shopify only. If you send an order to both us, and Shopify, this could be duplicated.
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 initialised 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 a quicker solution, 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) - This should be called at least once per “session”, e.g. the first time opening the app and signing in. It ensures the shopper is auto-enrolled and triggers any relevant rules (e.g. points for joining the program)
Show points & rewards
In the above response, we will show the points_approved, any claimed rewards and available_rewards - examine the
can_redeemproperty to know which rewards a customer currently has the points to redeem. We also show the available activity rules.
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 other endpoints (e.g. social follows).
Earn points on purchases
Shopify checkout - LoyaltyLion auto-receives the orders. No action needed.
Custom checkout - post with Create Order.
Please note that custom placed orders don't support line-items, so tracking usage of product rewards, rule modifiers, etc won't work
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 SDK App Embed, and use the Theme Editor page option to create a more standardised page that can be customised via CSS. If you want a more custom experience, components can be embedded individually, as found in the SDK documentation, and customised via 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 non-Shopify orders and refunds via Create/Update Order.
Post custom actions via Create Activity.
Sign customer auth tokens as described under API Authentication.
Commonly used webhooks
Checklist
Surface | Must Implement | API Docs |
POS | Initialize session, create/update orders, redeem rewards | |
Mobile | Initialize session, complete rules, redeem rewards | |
Headless Web | Initialize session, redeem voucher/free product | |
Shopify Theme | Install SDK, use loyalty page and modals |