Developer DocsLoyalty ConsoleSupport

Codes

The Codes module lets you upload unique codes into a pool and reward users when they submit one. Useful for on-pack promos, customer service gestures, and offline campaigns.

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.

Modules are sold separately and not included in the Loyalty Engine core platform licence. For pricing and details, contact your account manager.

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 – Codes given out by the Loyalty Engine when a user claims a reward, to be redeemed elsewhere (e.g., ecommerce checkout).

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.

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.

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

1

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.

2

Create an event type

Create a custom event type 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 with a code property.

  4. Turn on the code pool enhancer for this event type. This ensures the Loyalty Engine validates submitted codes against your pools when an event of this type is reported.

Example JSON6 event schema
{
  "type": "object",
  "$schema": "http://json-schema.org/draft-06/schema#"
  "properties": {
    "code": {
      "type": "string",
      "description": "The code submitted by the user"
    }
  },
  "required": ["code"]
}
Creating an event type to use for code submissions.
3

Create a code pool

  1. Go to Events > Code Pools > Create.

  2. Upload or add the list of you want to use.

  • Codes in a pool can only be redeemed once.

Creating a code pool representing unique codes printed on the inside of Pepsi Max 500ml labels.
4

Create a reactor

Create a reactor 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 for and choose the relevant code pool the submitted code should be checked against.

  4. Configure any reactions (e.g., award points, issue a voucher).

Awarding 500 points when a SUBMITTED_CODE event is reported which includes a code from the Pepsi Max 500ml code pool.
5

Test the flow

  1. Report an event 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.

Simulating a code submission by manually reporting a SUBMITTED_CODE event with a code from the Pepsi Max 500ml code pool.

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.

PreviousBadgesNextIntegrations

Last updated

Was this helpful?