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.

---

Overview

Vouchers are rewards that users actively redeem to receive a discount, free item, or other benefit. Unlike Offers, which are automatically applied when a member is identified at POS, Vouchers require the user to take action — such as claiming a reward in the loyalty app or microsite and then scanning or entering the voucher at checkout.

Each voucher has a unique code that must be validated by your POS or ecommerce platform through the Rewards API before it can be applied. Once validated, the response will include a discounts object describing how to apply the reward (for example, “£5 off” or “free coffee”).

Vouchers are typically used for:

• One-off rewards (e.g. £5 off your next purchase)

• Specific incentives (e.g. free item, birthday gift, prize redemption)

• Limited-use or time-bound promotions

Offers, by contrast, are “always on” discounts that apply automatically to eligible users and do not require redemption.

---

Context

Rewards & benefits

See Understanding rewards & benefits.

When a user gets a voucher-type reward, a benefit representing the voucher is added to their account.

Voucher codes

A voucher code is assigned to a 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 actions

• Redeem a benefit: A benefit has an inferred state based on the presence of one or more timestamps. A voucher code can only be validated or burned if the benefit is in the redeemed state. See Benefit lifecycle 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.