Redeeming vouchers

How to validate and burn vouchers issued by the Loyalty Engine's voucher management system.

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

---

Context

Rewards & benefits

See Understanding rewards & benefits.

When a user gets a voucher reward, a benefit representing the voucher is associated with their account.

Voucher codes

A voucher code is assigned to a voucher benefit when it is created, which is used for validation and burning.

The assigned voucher code can either be randomly generated by the Loyalty Engine (one-time voucher codes) or assigned from a pool of pre-determined codes (code pools). See Vouchers for more information on the various code types.

Voucher discounts

A voucher's associated reward contains the information regarding the actual discount a voucher offers.

The discount can be an absolute, percentage or fixed amount, and can be applicable to the entire transaction or a particular product SKU.

For more advanced discount logic, the discount can carry a SKU which correlates with a SKU in your POS system that should be added to the transaction to apply a discount.

See Discount configuration for more information on how discounts work, as well as the discounts API reference.

Voucher actions

• Redeem a benefit: A benefit has an inferred state based on the presence of one or more timestamps. A voucher can only be validated or burned if its associated benefit is in the redeemed state. See Benefits for more information. POST /commands/redeem_benefit redeems a benefit and makes it ready for validation.

• Validating and burning a voucher code: POST /commands/validate_voucher verifies the voucher’s validity, associated reward, and discount details and marks the voucher as used (burnt),

  • To validate a voucher code without burning it at the same time, set allowFutureValidation = true when calling the validate voucher command.

---

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

Redeem & retrieve voucher(s)

• Voucher code flow: User redeems voucher themself, and provides code directly.

• Voucher selection flow: Retrieve the user's benefits with GET /benefits and the relevant filter(s) applied, and let the user select a benefit from the list. If the benefit is not already redeemed, use POST /commands/redeem_benefit to redeem it. Then, retrieve the benefit with GET /benefits/{id} and get the associated voucher code (data.code.value).

3

Validate and burn voucher

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

4

Apply discount

Apply the discount(s) specified in the validate voucher API response to the transaction in POS.

5

Complete the transaction

Take payment (if applicable) and complete your transaction.

---

Voucher redemption notes

• Always validate/burn 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).

---

FAQs

What happens if a voucher is validated, but the transaction then fails (payment declines, network error etc.)?

At this time it is not possible to 'unburn' a voucher. Ensure a sufficient customer service escalation process exists to account for and handle this edge case manually.

Can POS automatically suggest available vouchers to users?

Yes, the 'select a voucher' flow referenced above describes how to use our APIs to enable POS to fetch and display available vouchers for the user, letting the cashier select and redeem on their behalf.

Can the same voucher be used across multiple transactions?

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