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

<table><thead><tr><th width="136.640625" valign="top">Flow</th><th width="163.03515625" valign="top">Best for</th><th valign="top">Pros</th><th valign="top">Cons</th></tr></thead><tbody><tr><td valign="top"><strong>Enter a voucher code</strong></td><td valign="top">In-store cashier POS / self-serve</td><td valign="top">Simple to implement, minimal integration needed</td><td valign="top">User must retrieve and enter/present code manually</td></tr><tr><td valign="top"><strong>Select a voucher</strong></td><td valign="top">Online checkout / app-led journeys</td><td valign="top">Seamless UX, no manual code entry</td><td valign="top">More complex integration; in-store it can slow service times and increase risk of misuse</td></tr></tbody></table>

***

## 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.&#x20;

#### Can the same voucher be used across multiple transactions?

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kbase.whitelabel-loyalty.com/developer/guides/integrate-with-pos/redeeming-vouchers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.