Integrating with POS

Learn how to integrate a POS system with the Loyalty Engine to enable points earning, voucher redemptions, and seamless loyalty interactions at checkout.

Introduction

This guide outlines the recommended implementation for integrating a POS system with the Loyalty Engine, covering multiple use cases including user lookup, earning and spending points, and voucher validation.

Key Loyalty Engine concepts to review

Before proceeding, we recommend reviewing key Loyalty Engine concepts in our Product Docs to understand the platform architecture:

• Introduction

• Events

• Reactors

• Vouchers

• Benefits

API Endpoints

The following API endpoints are referenced in this document. Take some time to familiarise yourself with each.

Function	API	API endpoint
Submit an order For reporting a transaction	Receipts	POST /orders
Report an event For reporting a transaction or spending points	Rewards	POST /events
Validate a voucher code For verifying or burning a voucher code	Rewards	POST /commands/validate_voucher
Retrieve a specific user For looking up a user and their authIdentifier	Rewards	GET /users/{id}
Retrieve a user’s wallet For retrieving a user's points balance and the voucher's in their wallet	Rewards	GET /users/{id}/wallet
Redeem a benefit For redeeming a voucher	Rewards	POST /commands/redeem_benefit

---

Reporting transactions to the Loyalty Engine

Reporting transactions to the Loyalty Engine lets you set up reactors and program logic to reward members in transactional loyalty programs.

You should report all transactions—including non-member transactions—to enable comparison of loyalty vs. non-loyalty performance on key metrics such as average spend.

There are two ways to report transactions:

Submit an order (recommended)

This approach uses the Receipts API to process transactions in a standardized way, designed specifically for transactional loyalty programs.

• The Receipts service receives and stores orders, and automatically reports an intrinsic ORDER_PLACED event to the Loyalty Engine when you call POST /orders.

• The Rewards service then handles loyalty aspects such as awarding points or vouchers.

• Setup and configuration of the Receipts service for your tenant must be completed by WLL. Do not proceed unless advised by your onboarding or success manager.

Implementation steps

1

Identify member

Retrieve the member ID via POS (QR code or manual input).

2

Lookup member

Call GET /users/{id} and cache the authIdentifier for further calls.

3

Report the transaction

After payment is confirmed, send the order to the Receipts service using POST /orders from your ERP.

• Include data such as transaction ID, total amount, line items, location ID and cashier ID.

• Never include PII in the request.

4

Once processed, the Loyalty Engine reports an ORDER_PLACED event and triggers reactors to award points based on earning rules.

Report a custom event

This approach uses the Rewards API to report transactions as custom events. It requires you to first create a custom event type corresponding to transactions and a reactor which then awards points when an event of this type occurs.

Implementation steps

1

Identify member

Retrieve the member ID via POS (QR code or manual input).

2

Report the transaction

After payment is confirmed, call POST /events from your ERP to report an event matching your custom event type for transactions.

• Include data such as transaction ID, total amount, branch ID, cashier ID, and basket details.

• Never include PII in the payload.

3

The Loyalty Engine processes the event and triggers reactors to award points or rewards based on earning rules.

---

Redeeming vouchers at POS

This section outlines how to validate and burn vouchers issued by the Loyalty Engine. Before implementing voucher redemption, ensure you are familiar with the Loyalty Engine’s concepts of vouchers, benefits, and the benefit lifecycle.

Voucher codes

Each voucher has a corresponding voucher code, which is used for validation and burning. POS systems can handle codes in different ways:

• One-time voucher codes (recommended): Generated by the Loyalty Engine and validated by POS via API.

• Voucher code pools with API integration: Pre-generated codes loaded into the Loyalty Engine, validated by POS via API.

• Voucher code pools without API integration: Codes generated and managed by POS in bulk, then loaded into the Loyalty Engine. Validation is handled entirely within POS.

Voucher actions

When a user purchases or receives a voucher reward, a benefit representing the voucher is associated with their account.

• Validate a voucher: POST /commands/validate_voucher verifies the voucher’s validity, burn status, associated reward, and discount details.

• Burn a voucher: If allowFutureValidation is false (default), the voucher is marked as used and future validation requests are rejected.

• To allow repeat validation (without burning), set allowFutureValidation = true in the request.

A voucher can only be validated or burned if its associated benefit is in the redeemed state.

Redemption journey

You can implement voucher redemption in two main ways:

1. Enter a Voucher Code

• User retrieves a voucher code from their wallet or email before checkout.

• They enter the code (online checkout) or present it at POS (in-store).

2. Select a Voucher

• User is shown a list of vouchers in their wallet at checkout.

• They select one to apply to the transaction.

Flow	Best for	Pros	Cons
Enter a voucher code	In-store cashier POS / self-serve	Simple to implement, minimal integration needed	User must retrieve and enter/present code manually
Select a voucher	Online checkout / app-led journeys	Seamless UX, no manual code entry	More complex integration; in-store it can slow service times and increase risk of misuse

Implementation steps

1

Identify member

Retrieve the member ID via POS (QR code or manual input).

2

Retrieve voucher(s)

• Voucher code flow: User provides code directly.

• Voucher selection flow: Retrieve user wallet with GET /users/{id}/wallet and let the user select.

3

Redeem and validate voucher

• If not already redeemed, use POST /commands/redeem_benefit.

• Then call POST /commands/validate_voucher to verify validity, burn the voucher, and retrieve discount details.

4

Apply discount

Apply the discount, specified in the voucher's associated reward, in POS and complete the transaction.

Voucher redemption notes

• Always validate/redeem before payment completion to prevent duplicate use across multiple locations.

• Voucher burns are final. If the transaction fails after redemption, customer service processes may be needed to issue a replacement.

• If you want to check a voucher without burning it, set allowFutureValidation = true. (Default is false.)

---

Redeeming points at POS

This section outlines how to allow users to redeem loyalty points for a discount directly at checkout. It requires you to first create a custom event type corresponding to points redemptions, and a reactor which then deducts the points when an event of this type occurs.

Implementation steps

1

Identify member

Retrieve the member ID via POS (QR code or manual input).

2

Retrieve points balance

Call GET /users/{id}/wallet to fetch the member’s points balance.

3

Confirm redemption amount

• Ask the user how many points they want to redeem.

• Use the program’s exchange rate to calculate the equivalent discount.

• Optionally, use POST /commands/test_reaction to confirm the points-to-cash ratio.

4

Apply discount in POS

Deduct the calculated amount from the transaction total.

5

Report redemption

Call POST /events to report an event matching your custom event type for points redemptions.

Points redemption notes

• Prevent over-redemption – Ensure POS does not allow users to redeem more points than their balance (the Loyalty Engine itself allows negative balances – if a user has 500 points, and you report an event which results in them having 1000 points deducted, the event will be reported successfully and their new balance will be -500 points).

• Deduct before payment – Report the redemption before payment is completed to prevent multiple simultaneous redemptions in different locations.

• Handle failed transactions – If a transaction is canceled or voided after points have been deducted, report a compensating event (e.g., POINTS_REFUND) with the inverse value to restore the balance.

• Never include PII in redemption event payloads.

---

FAQs

Can multiple redemptions happen at the same time across different locations?

Yes, but without safeguards, a user could potentially redeem their points or vouchers multiple times before the Loyalty Engine updates their balance. To prevent this:

• Always validate vouchers immediately before applying them to the transaction.

• Deduct points before transaction completion to prevent double-spending.

What happens if a user redeems points, but their transaction fails?

• If the redemption was voucher-based, vouchers cannot be refunded, but customer service may issue a replacement manually.

• If the redemption was voucherless (points as a payment method), an event-based reversal (e.g., POINTS_REFUND) should be reported to restore the user’s balance.

Can we customise the earn rate or redemption value for points?

Yes, the earn rate (e.g., 1pt per £1) and redemption value (e.g., 100pts = £1) are set via reactors and can be fully customised in the Loyalty Engine.

Can POS automatically suggest available vouchers to users?

Yes, cashier-led voucher redemptions allow POS to fetch and display available vouchers for the user, letting the cashier select and redeem on their behalf.

What if a voucher is applied, but the customer decides not to complete the purchase?

• If the voucher has already been validated and marked as used, it cannot be automatically reinstated.

• If this is a potential issue, consider using allowFutureValidation: true in the API request to check voucher eligibility before committing it.

Can the same voucher be used across multiple transactions?

No, vouchers are single-use by default and are marked as “burned” once validated.