# Codes

## What is the Codes module?

The Codes module allows you to **create and manage pools of unique codes** that can be validated when users submit them through your program.

When a user submits a code:

1. The Loyalty Engine checks if the code exists in the pool and hasn’t been used.
2. If valid, a reactor is triggered (e.g., awarding points or issuing a voucher).
3. The code is marked as used and can’t be redeemed again.

{% hint style="info" %}
Modules are sold separately and **not included** in the Loyalty Engine core platform licence. For pricing and details, contact your account manager. 
{% endhint %}

{% hint style="warning" %}

#### Not the same as voucher code pools

* **Codes module (this article) –** Used when you already have a pool of unique codes (e.g., printed on packaging, distributed by support teams). Users submit the code into your program, and it’s validated.
* [**Voucher code pools**](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/rewards-and-points/rewards/reward-types/vouchers/voucher-code-pools) **–** Codes given out by the Loyalty Engine when a user claims a reward, to be redeemed elsewhere (e.g., ecommerce checkout).
  {% endhint %}

### Example use cases

* **On-pack promotions**

  Print unique codes on product packaging (e.g., under caps or inside boxes, even on receipts). Users scan or enter them in your app or website to earn points or vouchers.
* **Customer service gestures**

  Provide one-off codes via your support team. When entered by the user, the code can trigger a reward such as bonus points.
* **Campaign rewards**

  Distribute unique codes via offline marketing (e.g., flyers, inserts at events). Users enter them to unlock loyalty rewards.

{% hint style="info" %}
If you only need a static single code (the same for all users), you don’t need the Codes module. You can create a custom event type and use payload conditions in your reactor to check for the code value.
{% endhint %}

### Key benefits

* **Control** – Ensure codes can only be used once.
* **Flexibility** – Use codes from any source (packaging, service, campaigns).
* **Integration** – Codes work with existing events and reactors in the Loyalty Engine.

***

## Using the Codes module

{% stepper %}
{% step %}

### Enable the module

Make sure the Codes module has been purchased and is enabled for your tenant. Contact your account manager for pricing and to activate the module.
{% endstep %}

{% step %}

### Create an event type

Create a [custom event type](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/events/event-types/creating-event-types) that will be reported when users submit codes.

1. In the Loyalty Console, go to **Events > Event Types > Create.**
2. Example name: `SUBMITTED_CODE`. (Admins can choose something more relevant, e.g., `PURCHASED_PRODUCT`)
3. Add a [payload schema](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/events/event-types/event-type-schemas) with a `code` property.
4. Turn on the [code pool enhancer](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/events/event-types/event-enhancers#code-pool) for this event type. This ensures the Loyalty Engine validates submitted codes against your pools when an event of this type is reported.

{% code title="Example JSON6 event schema" %}

```json
{
  "type": "object",
  "$schema": "http://json-schema.org/draft-06/schema#"
  "properties": {
    "code": {
      "type": "string",
      "description": "The code submitted by the user"
    }
  },
  "required": ["code"]
}
```

{% endcode %}

<figure><img src="https://1999217057-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEFmrMvu6tg0ZiSX9SGEq%2Fuploads%2Fb15jIev43wFxUiVuip4D%2FScreenshot%202025-09-26%20at%2020.18.11.gif?alt=media&#x26;token=8280a09e-ac6d-446d-bc99-88737e5783d6" alt=""><figcaption><p>Creating an event type to use for code submissions.</p></figcaption></figure>
{% endstep %}

{% step %}

### Create a code pool

1. Go to **Events > Code Pools > Create.**
2. Upload or add the list of [unique codes](#user-content-fn-1)[^1] you want to use.

* Codes in a pool can only be redeemed once.

<figure><img src="https://1999217057-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEFmrMvu6tg0ZiSX9SGEq%2Fuploads%2FzwN8zxRBFKMv6OVUPfPP%2FScreenshot%202025-09-26%20at%2020.15.47.gif?alt=media&#x26;token=f40ad2ea-6e4e-4409-a26e-440685f8fbcb" alt=""><figcaption><p>Creating a code pool representing unique codes printed on the inside of Pepsi Max 500ml labels.</p></figcaption></figure>
{% endstep %}

{% step %}

### Create a reactor

[Create a reactor](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/reactors/creating-reactors) that will run reactions when a code is submitted matching a code from your code pool.

1. Go to **Events > Reactors > Create.**
2. Choose the event type you created earlier (e.g., `SUBMITTED_CODE`) as the trigger.
3. Add a [payload condition](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/reactors/conditions) for ['Code Validity'](#user-content-fn-2)[^2] and choose the relevant code pool the submitted code should be checked against.
4. Configure any [reactions](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/reactors/reactions) (e.g., award points, issue a voucher).

<figure><img src="https://1999217057-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEFmrMvu6tg0ZiSX9SGEq%2Fuploads%2FKcqs3iXQPwv5YkvDtw8K%2FScreenshot%202025-09-26%20at%2020.21.46.gif?alt=media&#x26;token=7a03b3e1-5821-4527-8244-5bad1597eb24" alt=""><figcaption><p>Awarding 500 points when a SUBMITTED_CODE event is reported which includes a code from the Pepsi Max 500ml code pool.</p></figcaption></figure>
{% endstep %}

{% step %}

### Test the flow

1. [Report an event](https://docs.whitelabel-loyalty.com/rewards.html#events-events-collection-post) of your custom type with a valid code from the pool in the payload.
   * The reactor should trigger.
   * The code should be marked as used in the pool.
2. Try submitting the same code again.
   * The reactor won’t trigger because the code is already used.
3. Try a code not in the pool.
   * The reactor won’t trigger.

<figure><img src="https://1999217057-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEFmrMvu6tg0ZiSX9SGEq%2Fuploads%2FnlRYKCNAoGQXgaELGfSE%2FScreenshot%202025-09-26%20at%2020.26.12.gif?alt=media&#x26;token=46bb07a9-0fa5-465a-967e-e700a5ab6498" alt=""><figcaption><p>Simulating a code submission by manually reporting a SUBMITTED_CODE event with a code from the Pepsi Max 500ml code pool.</p></figcaption></figure>
{% endstep %}
{% endstepper %}

#### Additional notes

* You can create multiple code pools (e.g., one per product SKU).
* Reactors can be linked to different pools to run different reactions (e.g., 100 points for SKU A, 200 points for SKU B, bonus voucher for SKU C etc.).
* You can edit a code pool at anytime after creating it by opening it in the Loyalty Console and pressing 'Edit' in the top right corner. You can:
  * Mark a code pool as 'inactive' to prevent any reactors validating against it to not run.
  * Top up the code pool with more codes if the pool runs low.
  * Remove codes from the code pool to prevent them being validated by a reactor.

[^1]: The codes don't \*need\* to be unique, you could paste in the same code 100 times - in which case that code would be able to be validated 100 times.

[^2]: If this condition is not showing in the block editor, you may have forgotten to enable the code pool enhancer on your custom event type (mentioned in step 2 above).