Skip to main content

Custom POS Integration Framework

Assessment Guide for Merchants

Mags Maras avatar
Written by Mags Maras
Updated today

Purpose

This document helps merchants assess whether a custom POS solution can integrate with LoyaltyLion's loyalty program. It outlines the technical prerequisites needed for common use cases, allowing merchants to self-qualify their POS capabilities.

Assessment Approach

For each desired use case below:

  1. Review the "POS System Requirements"

  2. Confirm your POS vendor supports these capabilities

  3. Verify you have (or can build) the backend integration components

  4. Check the LoyaltyLion API prerequisites

Key Principle: LoyaltyLion provides the loyalty program APIs. The merchant's POS system must provide the UI rendering, data input, and integration layer capabilities.

Common Use Cases & Requirements

1. Display Customer Points Balance

Business Value: Allow store associates to inform customers of their current points balance at checkout.

POS System Requirements:

  • Ability to capture customer identifier (email, customer ID) at the POS terminal

  • Ability to render custom dynamic text/numbers on the terminal display

  • Network connectivity to make external API calls

Backend/Integration Requirements:

  • Backend server to securely call LoyaltyLion Headless API (POS cannot call directly with auth tokens)

  • Ability to map customer identifier to Shopify merchant_id

  • Optional: Caching layer to reduce API calls for repeated lookups

LoyaltyLion API Prerequisites:

  • Initialize Session endpoint (channel=pos)

  • Returns points_approved field

Potential Blockers:

  • POS has locked-down UI with no custom display capabilities

  • POS cannot make external network requests

  • No ability to build/host middleware server

2. Display Available Rewards

Business Value: Show customers which rewards they can currently redeem based on their points balance.

POS System Requirements:

  • Ability to capture customer identifier

  • Ability to render a list/menu of items (reward names, points costs)

  • Ability to indicate which items are available vs. unavailable (e.g., different colors, enabled/disabled state)

  • Network connectivity

Backend/Integration Requirements:

  • Middleware to call LoyaltyLion Headless API

  • Logic to parse available_rewards array and filter by can_redeem property

  • Optional: Handle reward stock availability

LoyaltyLion API Prerequisites:

  • Initialize Session endpoint

  • Returns available_rewards array with can_redeem boolean

Potential Blockers:

  • POS can only display static text, not dynamic lists

  • No way to distinguish available vs unavailable items in UI

  • POS UI has item count limits (e.g., "can only show 5 items")

3. Redeem Voucher/Discount Rewards

Business Value: Allow customers to apply loyalty rewards as discounts at POS checkout.

POS System Requirements:

  • All requirements from Display Available Rewards above

  • Ability to accept staff/customer selection of a reward

  • Ability to apply a discount code or percentage to the current transaction

  • Network connectivity

Backend/Integration Requirements:

  • Backend server to call Redeem Reward endpoint

  • Ability to apply discount to cart (either via a voucher code or manual discount application)

Potential Blockers:

  • POS discount system doesn't accept external codes / has no way to apply an arbitrary discount to the cart

  • No mechanism for staff to trigger reward redemption

  • POS discount UI is not accessible from custom integration

4. Award Points for In-Store Purchases

Business Value: Customers earn loyalty points on POS purchases.

POS System Requirements:

  • None specific (orders flow through Shopify or are sent to LoyaltyLion via API)

Backend/Integration Requirements:

  • POS must sync orders to Shopify OR merchant is willing to send all POS orders to LoyaltyLion via our Admin API

  • Consistent customer identification between POS and Shopify/LoyaltyLion

    • merchant_id must be the same, or at least matching email addresses

Critical Constraint:

⚠️ DO NOT send orders directly to LoyaltyLion if they're also going to Shopify - this will duplicate points awards.

Potential Blockers:

  • POS system has no way to sync orders to Shopify AND merchant is unable/unwilling to build a custom sync to send POS orders to LoyaltyLion Admin API

  • If syncing to Shopify:

    • Orders sync to Shopify but without customer attribution

Integrating LoyaltyLion with a custom ERP-based POS that doesn't sync to Shopify is technically possible, but it's a significant undertaking and has some functional constraints. Please refer to Appendix A: Backend Integration (non-Shopify) for further information.

If your POS could potentially sync to Shopify, but doesn't currently, it is recommended that you explore this option. This would provide a much simpler integration path, full line-item support, and lower total cost of ownership.

Examples:

  • NetSuite has native Shopify integration

  • SAP Business One has Shopify connectors

  • Many ERPs use middleware like Celigo or Commercient

This option eliminates the need for custom Admin API integration and unlocks full LoyaltyLion functionality.

5. Display Claimed Rewards (Already Redeemed)

Business Value: Show store associates which rewards customer has already claimed but not yet used.

POS System Requirements:

  • Ability to capture customer identifier

  • Ability to render a list of items (reward names, codes/SKUs)

  • Network connectivity

Backend/Integration Requirements:

  • Middleware to call Initialize Session endpoint

  • Logic to parse claimed_rewards array

  • Optional: Display format for voucher codes vs product rewards

LoyaltyLion API Prerequisites:

  • Initialize Session endpoint

  • Returns claimed_rewards array

Potential Blockers:

Universal Technical Requirements

All POS integrations require:

Authentication & Security

  • Secure server environment to store LoyaltyLion API credentials

  • Middleware/proxy to handle authentication (POS cannot securely store tokens)

  • HTTPS for all API communications

Customer Identification

  • Consistent customer identifier across all channels (email or Shopify customer ID)

  • POS must use Shopify merchant_id (customer ID) in all LoyaltyLion API calls

    • Email is technically OK but is vulnerable to typos, etc

Backend Infrastructure

  • Server to proxy requests between POS and LoyaltyLion APIs

  • Error handling for API failures (network, timeouts, invalid responses)

  • Optional but recommended: Request caching to improve performance

Appendix A: Backend Integration (non-Shopify)

Refer to this appendix when you have:

  • Custom POS integrated with an ERP system (NetSuite, SAP, Dynamics, Acumatica, etc.)

  • POS orders stored only in the ERP

  • No synchronisation of POS orders to Shopify

This scenario requires using LoyaltyLion's Admin API instead of relying on automatic Shopify order sync.

Critical Concept: Where Customer Records Live

Your ERP is the "golden source" for customer identity, NOT LoyaltyLion.

LoyaltyLion does not create or manage customer accounts. Your ERP/POS system is responsible for:

  • Creating customer accounts

  • Managing customer authentication

  • Maintaining the definitive customer record

LoyaltyLion simply tracks loyalty data (points, rewards, tier status) linked to your customer IDs.

Key implication: There is no "create customer account" API call. Customers are enrolled in the loyalty program automatically when you send their first activity (like a signup event or order) to LoyaltyLion.

Integration Requirements

1. Backend Middleware Server (Critical)

You MUST build and maintain a secure backend server to:

  • Store LoyaltyLion API credentials

  • Proxy requests between POS/ERP and LoyaltyLion APIs

  • Handle authentication and token signing

The POS cannot call LoyaltyLion APIs directly. This is a security requirement.

2. Consistent Customer Identity

You must use a single, unchanging customer identifier across all systems. This is typically:

  • The ERP's internal customer database ID

  • Or a unique customer number from your system

This same ID must be used in every LoyaltyLion API call (orders, activities, customer lookups).

Common failure mode: Using email in some places and customer ID in others breaks the integration.

3. Customer Enrolment Process

When a customer creates an account in your POS/ERP:

  1. Your system creates the customer account (you own this)

  2. You send a $signup activity to LoyaltyLion via Admin API

  3. LoyaltyLion creates the customer's loyalty record and enrols them

  4. Customer can now earn and spend points

Without the $signup event, customers remain as "guests" and cannot participate in the loyalty program, even if orders are sent to LoyaltyLion.

4. Order Tracking via Admin API

For every POS transaction, you must POST order data to LoyaltyLion's Admin API:

  • Order total, shipping, payment status

  • Customer identifier (must match signup event)

  • Any discount codes used

  • Order date and status

Critical limitation: Custom orders sent via Admin API do not support line-items.

What this means:

  • You cannot track which specific products were purchased

  • Product-specific loyalty rules won't work (e.g., "double points on shoes")

  • Free product rewards cannot be properly validated

  • Collection-based rules won't trigger

If you require greater sophistication than “points for the basket total” then this represents a significant limitation, and you should instead consider synchronising orders to Shopify.

5. Voucher/Discount Code Requirements

If you require redemption, then your POS must:

  • Support applying external discount codes at checkout

  • Allow bulk creation of 500+ discount codes per reward type

  • Import these codes into LoyaltyLion before rewards can be redeemed

If your POS doesn't accept arbitrary external discount codes, voucher rewards cannot be implemented.

Related Articles
Skio - Integration Manual
Stay.ai - Integration Manual
Loop - Integration Manual
Shopify Point of Sale (POS) integration
Omnichannel Integration Overview
Did this answer your question?