API ReferenceProduct DocsLoyalty ConsoleSupport

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.

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

References to our API documentation are included throughout this guide. Relevant API calls and commands:

Function
API endpoint

Retrieve a user’s wallet

Points and vouchers

GET /wallets/{userId}

List all benefits

Instances of purchased vouchers

GET /benefits

Redeem a benefit Voucher redemption

POST /benefits/{benefitId}/redeem

Validate a voucher code

POST /benefits/validate

Report a transaction or points redemption

POST /events

Test points-to-cash ratio

POST /test-reaction

POS integration use cases

Integrating a POS system with the Loyalty Engine enables a variety of loyalty-related interactions at checkout. The specific use cases outlined in this document include:

Use case
Info

User lookup

A cashier retrieves a customer’s loyalty balance and available vouchers in their wallet by scanning or entering a member ID.

Earning points

Customers earn points on transactions when their member ID is scanned at checkout.

Spending points Voucherless redemptions

Users spend points directly as a currency for discounts at checkout.

Spending points Voucher redemptions (user-led)

Users exchange points for discount vouchers in-app, then present a voucher code to the cashier for redemption.

Spending points Voucher redemptions (cashier-led)

The cashier retrieves and redeems vouchers from the customer’s wallet without the need for the user to present a code.

Voucher validation and redemption

POS systems can validate and apply discount vouchers in multiple ways:

  • One-time voucher codes: Codes are generated by the Loyalty Engine and looked up in the POS system via API.

  • Voucher code pools (API integration): Pre-generated codes are loaded into the Loyalty Engine, with POS validating the code in real time.

  • Voucher code pools (no API integration): POS generates and manages codes in bulk, with validation handled entirely within the POS system.

These use cases can be combined depending on the desired customer journey and available technical resources. The document provides detailed implementation steps for each approach.

1. User lookup – retrieve loyalty balance and vouchers

Use case:

  • A cashier retrieves a user’s points balance and available vouchers at checkout.

Implementation steps:

  1. Retrieve the member ID by entering or scanning it into POS.

  2. Use the Retrieve specific wallet API call to get the user’s points balance and available vouchers.

  3. Display the retrieved information to the cashier, allowing them to inform the user of their points balance and (optionally) any applicable vouchers.

2. Earning points – reporting a transaction

Use case:

  • A user scans their member ID at checkout and earns points based on their transaction.

Implementation steps:

  1. Retrieve the member ID via POS.

  2. Once the transaction is completed and payment is confirmed, report the transaction to the Loyalty Engine using the Report an event API call to report a TRANSACTION custom event.

  3. Include relevant data such as total amount spent, transaction ID, branch ID, cashier ID, and basket details etc. – whatever data points the program plans to reward, or needs to track, should be included in the payload. Never include PII in the payload.

  4. The event is processed, and any applicable reactors trigger to award points based on the program’s earning rules.

3. Spending points at POS

Users can redeem points using one of three approaches.

3.1 Voucherless redemptions – using points as a payment method

Use case:

  • A user redeems their points directly for a discount at checkout.

Implementation steps:

  1. Retrieve the user’s points balance using the Retrieve specific wallet API call.

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

  3. Convert points to a monetary discount using the program’s exchange rate. You can use the Test reaction API call to confirm the points-to-cash ratio.

  4. Apply the discount in POS.

  5. Report the redemption using the Report an event API call to deduct points from the user’s balance with a REDEEMED_POINTS custom event.

Notes:

  • Ensure POS does not allow users to redeem more points than they have available, as negative balances are possible in the Loyalty Engine.

  • Do not wait until the transaction is complete before deducting points—this prevents users from attempting multiple redemptions in different locations simultaneously. If the transaction is cancelled or voided before it completes but after you have reported the event deducting points, report another event (i.e. POINTS_REFUND) with the inverse value to reverse the deduction.

3.2 Voucher redemptions – user-led

Use case:

  • A user redeems points for a discount voucher in-app / website and presents a voucher code at checkout.

Implementation steps:

  1. The user generates a voucher in-app before arriving at checkout.

  2. At checkout, they present the voucher code to the cashier.

  3. The cashier enters the voucher code into POS.

  4. Use the Validate voucher code API call to verify the voucher, mark it as used and retrieve its associated discount details (if applicable).

  5. Apply the discount in POS.

  6. The Loyalty Engine marks the voucher as used to prevent further use.

Notes:

  • If the transaction fails (e.g., the user doesn’t complete payment), a customer service process may be needed to issue a replacement voucher as voucher redemptions are irreversible.

  • If you want to lookup the voucher code without marking it as used (thus allowing it to be validated again), add allowFutureValidation: true in the body of the Validate voucher code API request.

3.3 Voucher redemptions – cashier-led

Use case:

  • The cashier retrieves and redeems the user’s vouchers directly within POS, without the user needing to present a code.

Implementation steps:

  1. Retrieve the user’s available vouchers using the List all benefits API call (with a user filter applied).

  2. Inform the user of their available vouchers and ask which one they would like to redeem.

  3. Redeem the voucher using the Redeem a benefit API call.

  4. Use the Validate voucher code API call to mark the voucher as used and retrieve its associated discount details (if applicable).

  5. Apply the discount to the transaction.

Notes:

  • Avoid waiting until the transaction is complete before validating and redeeming the voucher. This helps prevent users from redeeming the same voucher in multiple locations simultaneously.

  • Voucher redemptions and validations are final and cannot be reversed. If a transaction fails after a voucher has been redeemed, a customer service process may be required to resolve the issue.

Best practices

  • Avoid race conditions: Deduct points or mark vouchers as used before completing the transaction to prevent users from attempting multiple redemptions simultaneously.

  • Ensure reversibility: If a transaction is cancelled, implement a reversal event to restore deducted points.

  • Monitor API rate limits: Ensure your integration handles rate limits effectively (current rate limits specified in our API docs).

FAQs

1. 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.

2. 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.

3. 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.

4. How can cashiers verify if a voucher is still valid before applying it?

  • Use the Validate voucher code API call before applying the discount.

  • This ensures the voucher is still available and hasn’t already been redeemed.

5. 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.

6. 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.

7. Can the same voucher be used across multiple transactions?

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

Last updated

Was this helpful?