Benefits

Learn how benefits work in the Loyalty Engine, including states, events, fulfilment flows, and how they’re handled across different reward types.

A benefit is a user-specific instance of a reward. When a user gets a voucher or gift card-type reward, 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 or Retrieve a benefit endpoint and are used to infer the benefit's current 'status' (no explicit status exists).

Status	Description
Created (Ready to redeem)	The data.createdAt timestamp is set. This is set when the reward is purchased and the benefit is created, after calling the Purchase a reward command.
Redeemed	The data.redeemedAt timestamp is set. This is set to the time and date when the benefit was redeemed after calling the Redeem a benefit command.
Validated	Applicable only when the benefit is a WLL VOUCHER. The data.code.validatedAt timestamp is set. This is set to the time and date when the benefit was first validated using the Validate a voucher code command. (if supported in your implementation). If allowFutureValidation = true was not set on the request when validating, the voucher moves straight to Burned status.
Burned	Applicable only when the benefit is a WLL VOUCHER. The data.burnedAt timestamp is set (note this is NOT in the code object but in the parent data object). This is the time and date when the benefit was validated.
Expired	Optional and only applicable when the benefit is a WLL VOUCHER. Set at the point of benefit creation, when the reward associated with the benefit has an expiry period defined. A benefit is expired when the current time is after data.expiresAt, and neither data.redeemedAt nor data.code.validatedAt are set.

Retrieve a benefit sample response

{
  "status": "success",
  "data": {
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "type": "VOUCHER",
    "createdAt": "2018-06-08T08:57:47.198Z",
    "redeemedAt": "2018-06-10T21:07:01.219Z",
    "expiresAt": "2019-06-08T08:57:47.198Z",
    "burnedAt": "2019-06-08T08:57:47.198Z",
    "reward": {
  ...
    },
    "owner": {
  ...
      }
    "code": {
      "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",
      "validatedAt": "2018-06-08T08:57:47.198Z",
      "value": "123ABC"
    }
  }
}

---

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 to learn how rewards and benefits are implemented in your program.