> For the complete documentation index, see [llms.txt](https://kbase.whitelabel-loyalty.com/developer/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kbase.whitelabel-loyalty.com/developer/guides/integrate-with-pos/redeeming-vouchers.md). # Redeeming vouchers {% hint style="info" %} 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**](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/rewards/reward-types/vouchers), [**benefits**](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/benefits), and the **benefit lifecycle**. {% endhint %} *** ## Overview Vouchers are rewards that users actively redeem to receive a discount, free item, or other benefit. Unlike [**Offers**](/developer/guides/integrate-with-pos/applying-offers.md), 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](/developer/guides/integrate-with-pos/processing-discount-objects.md) 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](https://docs.whitelabel-loyalty.com/rewards.html#header-understanding-rewards-and-benefits). When a user gets a voucher-type [reward](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points), 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](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/rewards/reward-types/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 [Benefits](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/benefits#benefit-lifecycle) for more information. [**`POST /commands/redeem_benefit`**](https://docs.whitelabel-loyalty.com/rewards.html#commands-benefit-redemptions-post) redeems a benefit and makes it ready for validation. * **Validating and burning a voucher code:** [**`POST /commands/validate_voucher`**](https://docs.whitelabel-loyalty.com/rewards#commands-voucher-validations-post) verifies the voucher’s validity, associated reward, and [discount details](/developer/guides/integrate-with-pos/processing-discount-objects.md) 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.
FlowBest forProsCons
Enter a voucher codeIn-store cashier POS / self-serveSimple to implement, minimal integration neededUser must retrieve and enter/present code manually
Select a voucherOnline checkout / app-led journeysSeamless UX, no manual code entryMore complex integration; in-store it can slow service times and increase risk of misuse
*** ## Implementation steps {% stepper %} {% step %} ### **Identify member** Retrieve the member ID via POS (QR code or manual input). {% endstep %} {% step %} ### **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`**](https://docs.whitelabel-loyalty.com/rewards.html#benefits-benefits-collection-get) 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`**](https://docs.whitelabel-loyalty.com/rewards#commands-benefit-redemptions-post) to redeem it. Then, retrieve the benefit with [**`GET /benefits/{id}`**](https://docs.whitelabel-loyalty.com/rewards.html#benefits-individual-benefit-get) and get the associated voucher code (`data.code.value`). {% endstep %} {% step %} ### **Validate and burn voucher** Call [**`POST /commands/validate_voucher`**](https://docs.whitelabel-loyalty.com/rewards#commands-voucher-validations-post) to verify validity, burn the voucher, and retrieve discount details. {% endstep %} {% step %} ### **Apply discount** Apply the [**discount**](/developer/guides/integrate-with-pos/processing-discount-objects.md)**(s)** specified in the validate voucher API response to the transaction in POS. {% endstep %} {% step %} ### Complete the transaction Take payment (if applicable) and complete your transaction. {% endstep %} {% endstepper %} *** ## 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.