Redeeming points

How to redeem a user's loyalty points for discounts at checkout.

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.

---

Pre-requisites

• Setup a custom event type, like REDEEMED_POINTS, and include points in the payload schema. You may optionally want to include data like transaction ID, store ID, cashier ID etc. in the payload too.

• Setup a reactor which triggers on your custom event type, and adjust's a user's points balance by $.points * -1.

---

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 – ensure this does not exceed the number of points in their balance.

• Use the program’s points redemption rate to calculate the equivalent discount. You may choose to store the redemption rate as a setting, so it can be updated easily in the loyalty config at any time without the need for POS updates (for example a key:value pair of pointsCurrencyValue:0.01 could indicate 1 point is worth 1 cent.)

4

Report redemption

• Call POST /events to report an event matching your custom event type for points redemptions, with the number of points being redeemed included in the payload.

• You may choose to fetch the member's points balance again immediately before reporting the event to ensure the points balance has not changed in the time it's taken the user to enter the number of points they want to redeem.

5

Apply discount in POS

Deduct the calculated amount from the transaction total.

---

Important 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

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

To handle transaction failures, setup another custom event type and reactor which is the reverse of the above instructions (e.g., POINTS_REFUND), and report that event when the failure occurs.