# Benefits

A benefit is a user-specific instance of a reward. When a user gets a voucher or gift card-type [reward](/product/loyalty-engine/rewards-and-points/rewards.md), the Loyalty Engine creates a **benefit**. A benefit represents the user’s individual entitlement to the value of that reward—for example, “£10 off your next purchase.”

Each benefit is uniquely tied to the user who purchased the reward and reflects a specific instance of that reward being fulfilled. A **Reward** defines the marketing container and eligibility requirements. A **Benefit** is the result of redemption—the actual value delivered to the user.

***

## Benefit lifecycle

The lifecycle of a benefit is tracked using a set of timestamps on the benefit itself. These timestamps can be found when calling the [List all benefits](https://docs.whitelabel-loyalty.com/rewards.html#benefits-benefits-collection-get) or [Retrieve a benefit](https://docs.whitelabel-loyalty.com/rewards.html#benefits-individual-benefit-get) endpoint and are used to infer the benefit's current 'status' (no explicit status exists).

<table><thead><tr><th width="139.08984375" valign="top">Status</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><strong>Created</strong> <em>(Ready to redeem)</em></td><td valign="top"><ul><li>The <code>data.createdAt</code> timestamp is set.</li><li>This is set when the reward is purchased and the benefit is created, after calling the <a href="https://docs.whitelabel-loyalty.com/rewards.html#commands-reward-purchases-post">Purchase a reward</a> command.</li></ul></td></tr><tr><td valign="top"><strong>Redeemed</strong></td><td valign="top"><ul><li>The <code>data.redeemedAt</code> timestamp is set.</li><li>This is set to the time and date when the benefit was redeemed after calling the <a href="https://docs.whitelabel-loyalty.com/rewards.html#commands-benefit-redemptions-post">Redeem a benefit</a> command.</li></ul></td></tr><tr><td valign="top"><strong>Validated</strong></td><td valign="top"><ul><li>Applicable only when the benefit is a WLL <code>VOUCHER</code>.</li><li>The <code>data.code.validatedAt</code> timestamp is set.</li><li>This is set to the time and date when the benefit was first validated using the <a href="https://docs.whitelabel-loyalty.com/rewards.html#commands-voucher-validations-post">Validate a voucher code</a> command. (if supported in your implementation).</li><li>If <code>allowFutureValidation = true</code> was not set on the request when validating, the voucher moves straight to <em>Burned</em> status.</li></ul></td></tr><tr><td valign="top"><strong>Burned</strong></td><td valign="top"><ul><li>Applicable only when the benefit is a WLL <code>VOUCHER</code>.</li><li>The <code>data.burnedAt</code> timestamp is set (note this is <strong>NOT</strong> in the <code>code</code> object but in the parent <code>data</code> object).</li><li>This is the time and date when the benefit was validated.</li></ul></td></tr><tr><td valign="top"><strong>Expired</strong></td><td valign="top"><ul><li>Optional and only applicable when the benefit is a WLL <code>VOUCHER</code>.</li><li>Set at the point of benefit creation, when the reward associated with the benefit has an expiry period defined.</li><li>A benefit is expired when the current time is after <code>data.expiresAt</code>, and neither <code>data.redeemedAt</code> nor <code>data.code.validatedAt</code> are set.</li></ul></td></tr></tbody></table>

<pre class="language-json" data-title="Retrieve a benefit sample response"><code class="lang-json">{
  "status": "success",
<strong>  "data": {
</strong>    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "type": "VOUCHER",
<strong>    "createdAt": "2018-06-08T08:57:47.198Z",
</strong><strong>    "redeemedAt": "2018-06-10T21:07:01.219Z",
</strong><strong>    "expiresAt": "2019-06-08T08:57:47.198Z",
</strong><strong>    "burnedAt": "2019-06-08T08:57:47.198Z",
</strong>    "reward": {
  ...
    },
    "owner": {
  ...
      }
<strong>    "code": {
</strong>      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": "2018-06-08T08:57:47.198Z",
<strong>      "validatedAt": "2018-06-08T08:57:47.198Z",
</strong>      "value": "123ABC"
    }
  }
}
</code></pre>

***

## Event reporting

The following events are reported automatically when the relevant commands are called:

* `PURCHASED_REWARD` → Reported immediately after a reward is purchased and benefit is created.
* `REDEEMED_VOUCHER` → Reported immediately after a WLL voucher benefit is redeemed.
* `BURNED_VOUCHER` → Reported immediately after a WLL voucher is burned.

***

## Flow by benefit type

#### 1. Digital gift card (via WLL fulfilment partner)

* Benefit is created on reward purchase.
* Code (usually a gift card URL) is immediately available via the **Get Benefit** endpoint.
* Redeeming the benefit is optional in WLL. You can use this step to mark it as used (e.g. removed from wallet).

#### 2. WLL voucher (static or code pool, no integration)

* Benefit is created on reward purchase.
* Code is **not revealed** until the benefit is redeemed.
* `REDEEMED_VOUCHER` event is reported on redemption.
* No `BURNED_VOUCHER` event is reported, as there is no validation step.

#### 3. WLL voucher (integrated, one-time code validation)

* Benefit is created on reward purchase.
* Code is **not revealed** until the benefit is redeemed.
* When the code is validated via the WLL API (e.g. POS checks the code), a `BURNED_VOUCHER` event is reported and `validatedAt` is updated.

***

## Front-end handling of benefits

How you implement and display benefits on your front end is up to you. For example, you might:

* Build a wallet-style interface to show benefits in the user profile
* Email benefit codes to users upon redemption
* Build a custom redemption flow in your app or website

If you're using the WLL Loyalty Microsite or Mobile App, contact [WLL Support](/product/services-and-support/wll-support/how-do-i-contact-support.md) to learn how rewards and benefits are implemented in your program.


---

# 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/product/loyalty-engine/rewards-and-points/benefits.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.