# 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**](/product/loyalty-engine/rewards-and-points/rewards/reward-types/vouchers/voucher-code-pools.md) **–** 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](/product/loyalty-engine/events/event-types/creating-event-types.md) 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](/product/loyalty-engine/events/event-types/event-type-schemas.md) with a `code` property.
4. Turn on the [code pool enhancer](/product/loyalty-engine/events/event-types/event-enhancers.md#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="/files/2uaISRobyfdBSipb49RJ" 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="/files/r7e9pTYnC844JSwzxm5k" 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](/product/loyalty-engine/reactors/creating-reactors.md) 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](/product/loyalty-engine/reactors/conditions.md) 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](/product/loyalty-engine/reactors/reactions.md) (e.g., award points, issue a voucher).

<figure><img src="/files/8RELMkWPFsaN26JrDSa3" 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="/files/EDX3Bzmsz3F4OPtP8lHm" 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).


---

# 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/modules/codes.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.