Vouchers are simple text codes that customers can use in your online store to redeem discounts or other special offers. You can communicate these codes to your customers through your campaigns.

The simplest way to insert a voucher into a campaign would be to use the same code for every customer. However, it is often desirable to send a unique code to every customer. The Vouchers feature allows you to load a pool of vouchers into Bloomreach Engagement, insert them into any campaign, and track their usage.

This guide will explain how to do so, and help you understand the extent of the possibilities offered by this feature.


Please note that this feature is only for showing personalized vouchers to your customers through campaigns and for tracking their use. It does not substitute your voucher system which applies the appropriate reductions when a voucher is used.

Import Voucher Codes

Importing vouchers is very easy, and similar to importing other kinds of data. A number of data sources can be used - for more information, see Imports . The only thing you need is a pre-generated list of voucher codes, in a single column, with a header. The codes need to be unique. If you try to import a code that is in the pool already, it will be ignored. Once you have the codes:

a. Navigate to Data & Assets -> Imports.

b. Click on the + New Import button in the top-right corner of your screen.

c. Click on the Vouchers button.

d. Select a pre-existing voucher pool to which you wish to add new vouchers codes, or create a new one by typing its name.


It's good practice to group vouchers and name your voucher pools in a manner that's meaningful and easy to identify, such as 10% Discount, 100 EUR off, or by campaign name.


Naming your vouchers

Your selected voucher name should be without spaces to avoid an error.

e. Select the data source you wish to use.

f. Click on Preview to double-check the Delimiter and Encoding settings of your import. The preview windows will show you the header and the first five rows.

g. Click on the Next button.

h. Assign the code ID to the column by dragging the blue box. For vouchers, you can only import one column containing the codes. Bloomreach Engagement doesn't support additional features such as voucher expiration, etc.

i. If you are importing from a URL, database or a Bloomreach Engagement analysis, you can schedule a repeated import in the next step.

j. Click on the Run Import button in the bottom-right corner of your screen.

k. Return to Data & Assets -> Imports to view the import and make sure all rows (vouchers) were imported correctly.

You can see all your imported voucher pools in Data & Assets > Vouchers.


Same voucher pools

You cannot import the same voucher code into multiple voucher pools

Use Vouchers

Before using vouchers for the first time, make sure that the use of a voucher for making a purchase - including the voucher code itself - is being tracked.

Go to Project Settings > Mapping > Vouchers and indicate where the voucher code is tracked once used. This will allow Bloomreach Engagement to know when a specific voucher was redeemed. If you, for example, track voucher codes as an attribute of event purchase named "voucher_code", the mapping should look like this:


Tracking for redeemed vouchers requires the mapped attribute to be a string.

Vouchers can be accessed via Jinja. The Personalization wizard (see the Personalization in Jinja guide for further details) can help you generate the correct syntax to:

Action TypeDescribtion
Assign available codeThis will select an available voucher code from the pool, change its status from available to assigned and display the voucher code in the campaign. The codes are assigned at the time of campaign execution e.g. weblayer being displayed to a customer or email campaign with the code is sent (including test campaigns). There is no limitation to the number of vouchers a customer can be assigned.
Count available codesThis will return the count of currently available codes within a voucher pool.
Count total codesThis will return the overall count of all codes within a voucher pool.

The latter two are useful for reporting purposes, such as sending automation notices through email or webhook when the number of available codes becomes too small.


Assigning available voucher codes

Every time you use the code vouchers['voucher_xy'].assign_available(), it will assign a voucher code from the pool, and by default, it will reuse it within the same email, SMS, or MMS to the same customer if you decide to use it multiple times within the same email/SMS/MMS.

In case you need to display different vouchers within your campaign to the same customer, you have to set the parameter cached to false in the format vouchers['voucher_xy'].assign_available(cached = false), and then a new voucher will be calculated for every occurrence within the individual campaign.

Note: Setting the cached parameter to false does not work within the preview email functionality. In preview, you will always see the same voucher, however, the customer will receive an email with a different voucher if you change the default with the cached parameter set to false.

To check if and when a voucher was assigned or redeemed, go to Data & Assets > Vouchers and select the Voucher pool.

How to use the same voucher code multiple times

The conventional way of assigning vouchers using the Engagement platform is using the Jinja code {{vouchers['voucherpool_name'].assign_available()}} This code will assign a voucher code from the pool at random. The platform will not track which code was assigned to which user out of the box, which restricts reusing the same code for the same user again in other/subsequent campaigns.

There are two common approaches how to reuse the same voucher code later:

  1. Adding it as a custom customer attribute and using {{ customer.attribute_name }} Jinja to call the voucher. There is no need for these codes to be unique.
  2. Assigning the voucher as a Custom event's attribute so it can be called through aggregate and used as many times as needed.

When to use what? The approach with Custom events gives an overview of what voucher was assigned to a customer and when. All that information, along with additional data, can be stored in Custom events.

1. Custom customer attributes to reuse voucher codes

This one is the simpler solution of the two, and all you have to do is create a new attribute from your Data Manager and give it a name that you can later use to identify it as a Voucher (voucher, temp_voucher, voucher_assigned, etc.).

This custom customer attribute can be populated in two different ways.

The first way is by the 'add attribute' node in Scenarios.

Instructions on how to assign vouchers using the ‘set attribute’ node will be provided later in this guide.

The second way you can assign voucher codes as attributes is to import them via the import Customers attributes as opposed to Vouchers import which is typically used for uploading vouchers.

Once the vouchers are updated, the attribute will look something like this.

From here it is as simple as using basic Jinja code {{ customer.voucher }} to display the Voucher code every time you need to display this particular code.

This solution will be best suited when you have a smaller number of customers you need to assign vouchers to. Because you will need to update this attribute every time you need to assign new vouchers.

2. Custom customer events to reuse voucher codes

Create a new event named voucher/voucher_assigned or something of your choice and give it attributes that you might want to later use to narrow down which campaign/flow the voucher code belongs to.

The key to the next step is the ‘Add Event’ feature you see in Scenarios. You need to place the ‘Add Event’ node before the email node so the voucher event is added.

Inside the ‘Add event’ node, you need to use Jinja to assign vouchers.

What the above node will do is add a ‘voucher’ event to every customer that passes through the node and it will have a voucher code in the ‘voucher_code’ attribute.

Then create an aggregate that will look for the last voucher event’s voucher code attribute for each customer. Further, narrow it down by attribute ‘type’ and ‘status’ to make sure the aggregate pulls only the latest voucher_code for the relevant campaign.

Once the aggregate is created, use the Jinja for this particular aggregate to call the voucher_code attribute on every occasion where you want to display the Voucher code.

What happens if you run out of assignable vouchers

Email campaignsThe rest of the campaigns will fail to be sent, generating campaign events with status = enqueue_failed
Web layersIf there are no codes to assign, web layers will not be displayed at all, and will not generate any events.