---
title: "Coupons"
slug: "coupons"
description: "The user manual provides comprehensive guidance on using the Antavo Management UI for managing loyalty programs."
updated: 2025-05-09T11:47:25Z
published: 2025-05-09T11:47:25Z
canonical: "docs.antavo.com/coupons"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.antavo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Coupons

Antavo’s Coupons module serves as a centralized platform for defining and managing all coupons within the loyalty program in one place. The coupon pools can be used across various modules, including [Rewards](/v1/docs/rewards), the [Offers](/v1/docs/offers), and [Workflows](/v1/docs/basic-concepts).

To access the module configuration page, search for Coupons under the Modules menu. The page will display the list of coupon pools configured within the module, along with the following details:

| **Name** | The name of the coupon pool |
| --- | --- |
| **Source** | The source of the coupon codes (*uploaded*, *generated*, *remote*, *bulk generation*) |
| **Type** | The type of coupons (*amount*, *percentage*, *free shipping*, *gift card*) |
| **Value** | The value assigned to the coupons |

![](https://cdn.document360.io/08a474ca-8fb4-4c3c-9cd8-665242086cd3/Images/Documentation/coupon-pool-list.png)

## Creating a new coupon pool

📓

You can access and display all the information configured in the Coupons module on the membership site through the [Display API](https://developers.antavo.com/reference/about-display-api), the [Entities API](https://developers.antavo.com/reference/about-entities-api) and the [Coupon API](https://developers.antavo.com/reference/about-coupon-api). Please work with your developers to implement the necessary calls for integration.

The following steps outline how to configure a new coupon pool through the UI. Alternatively, this can also be achieved via the `/v1/coupon-pools` endpoint of the [Coupon Pools AP](https://developers.antavo.com/reference/post_v1-coupon-pools#/)I.

- Click the **Create coupon pool** option in the sidebar
- Add the **name** of the coupon pool

### Coupon source

- Select one of the four **coupon sources***: uploaded*, *generated, remote* or *bulk generation*.

![](https://cdn.document360.io/08a474ca-8fb4-4c3c-9cd8-665242086cd3/Images/Documentation/sources.png)

#### Generation and bulk generation

If you want Antavo to generate codes, define the coupon pattern using placeholder characters:

- `#` for a digit (0-9)
- `@` for an alphabet character (a-z)
- `^` for a capital alphabet character (A-Z)
- `*` for an alphanumeric character
- `$` for a capital alphanumeric character

All other characters should be added as literals (eg. if you set '*@##COUPON*’, a generated coupon code could be G11COUPON or T35COUPON).

If you would like to assign a generic coupon code to all customers, don’t use pattern characters, only literals (eg. if you set ‘SPRINGCOUPON’, all coupon codes to each customer will be generated as SPRINGCOUPON)

However, when defining the pattern of bulk-generated coupons, you must add at least 4 variables, which ensures that coupons can serve high demands.

⚠️

Each coupon pool must have a unique pattern.

#### Bulk-generation settings

Coupon pools with bulk-generated sources offer specific settings for customization:

- **Exclude characters** Specify any characters, separated by commas, that you want to exclude from coupon code generation to prevent confusion of similar characters (eg. *O* and *0* or *1* and *I*). Remember to list both lowercase and uppercase letters separately.

📓

As you add new excluded characters, the **Number of unique combinations** information under the Pattern configuration field dynamically calculates the total number of coupon combinations available .

![](https://cdn.document360.io/08a474ca-8fb4-4c3c-9cd8-665242086cd3/Images/Documentation/coupon-calculation.png)

- **Exclude phrases** List specific phrases that you wish to exclude from coupon code generation to avoid unintentional or inappropriate text usage.
- **Number of coupons** Define the number of coupons to generate, ranging from 1 to 100 million. Note that the number of coupons generated must not exceed 1% of the possible variations within the coupon pattern. This prevents the customers from making lucky guesses on valid coupon codes. The maximum number of coupon codes is determined by the coupon pattern and is displayed in the help text. Be aware that this number might decrease if certain characters or phrases are excluded.

![](https://cdn.document360.io/08a474ca-8fb4-4c3c-9cd8-665242086cd3/Images/Documentation/bulk-generation-settings.png)

#### Upload

Select the **upload option** if you want to [upload](/v1/docs/coupons#Uploading-coupons) a set of coupons for distribution. Each coupon code can only be uploaded to one coupon pool; duplications are skipped automatically during the import process.

#### Remote

If you’d like to maintain control over coupon management, you can set a **callback URL endpoin**t that serves Antavo with coupon codes to issue. When generated by the external system, it is also determined to whom the coupon is assigned, thus facilitating validation. The process requires the URL endpoint to receive `POST` requests from Antavo and responds with a coupon code.

Whenever the system requests a code, it will send the following request:

```json
{
"api_key" => "DEMODEMODEMOSDJDSIFDKDF", 
   "coupon_percentage" => "20", 
   "value" => "THE COUPON VALUE", 
   "customer" => "53626328374843843", 
   "type" => "percentage"
}
```

- The API key must be checked against a stored API key to prevent any malicious requests to generate coupon codes
- The percentage value of the percentage-type coupon
- The value of the amount-type coupon
- Customer identifier
- Any other potential values

As a response, the system expects the code in the following format:

```json
{
   "code" => "COUPON CODE"
}
```

If the system receives the coupon code, it is automatically passed on to the customer.

### General settings

- Define the **type of coupons** in the pool
  - Fix amount
  - Percentage-off
  - Free shipping
  - Gift card Customers can use gift card coupons at multiple checkouts until the entire monetary value is spent.
- Define the **value of the coupons** in the pool - *not applicable to free shipping coupons*
- Define the **currency** of the coupons*- only applicable for gift card coupons*

### Restrictions

- Add a **minimum value***– only applicable to gift card coupons* The gift card will be invalidated if the balance falls below this amount. For example, if a $100 gift card has its minimum value of $1 and the customer uses the gift card to pay $99.5, then the card balance falls below $1 and the card will be voided.
- Add a **minimum redemption value** *- only applicable to gift card coupons* The customer must use at least this amount of the gift card each time they redeem it at checkout to reduce the basket value. For example, if the customer wants to redeem $10 of its $100 gift card to pay partially at purchase, but the minimum redemption value is $15, the redemption would fail with an error message.
- Add the **currency** of the coupon - *only applicable to gift card coupons* If a currency is set, the coupon reward can only be assigned to a customer who has the same value saved in their Currency customer attribute. This can be checked under the [Personal information tab](https://docs.antavo.com/docs/customer-insights#personal-information) in the customer profile.
- Add a **purchase minimum** Restrict the usage of a coupon to a minimum basket value.
- Set an **expiration period** The coupon code's expiration date is calculated from when the coupon was assigned to the customer.
- Add **stores** Pre-defined offline stores created/listed within the [Stores module](/v1/docs/stores) can be used to localize the validity of the coupon codes.
- Decide if you want to **assign an aggregated coupon** Tick the checkbox to have the same coupon code assigned each time this coupon pool issues a coupon for one specific customer.
- Add **products** It is possible to create and redeem coupons for individual products by selecting item(s) (previously added in the [Product catalog](/v1/docs/product-catalog) module) to which the discount should apply.

⚠️

Please keep in mind that **Antavo doesn’t handle coupon validation at checkout**. We provide all the information about restrictions type and the value of the coupon through API endpoints, but you need to take care of checking the eligibility and reducing the total value of the basket when the customer redeems the coupon code.

### Pass template

If you use the [Wallet module](/v1/docs/wallet), you might want to select a pass template to be assigned to the coupons in the currently configured pool. The coupon pass that customers can add to their wallet application will be generated based on the selected pass template.

### User group

If you use the [User groups](/v1/docs/user-groups) module and have enabled the *Coupon pool* and *Coupons* entities in the settings, you need to assign a group to the coupon pool. Unauthorized users won’t be able to access the coupon pool in the Management UI and the corresponding coupon statistics.

![](https://cdn.document360.io/08a474ca-8fb4-4c3c-9cd8-665242086cd3/Images/Documentation/coupon-group.png)

### Saving a coupon pool

Don’t forget to click the **Save** button at the end of the configuration process.

## Uploading coupons

- Click the **Upload coupons** option in the sidebar You’ll be redirected to the coupon import page of the [Imports module](/v1/docs/imports).
- Click **Choose file** to upload a CSV format file with one code in each row You can find the data fields you can include in the CSV in the *Name* column under the **Fields** section.
- Click**Upload** at the bottom of the page
- [Configure the file import](/v1/docs/imports#creating-a-new-import) as per your need, and ensure the correct coupon pool is selected in the [**Coupon pool dropdown field**](/v1/docs/imports#module-options) under Module options.
- Click **Start import**

![](https://cdn.document360.io/08a474ca-8fb4-4c3c-9cd8-665242086cd3/Images/Documentation/uploadcoupons.png)

Right after the import is completed, coupons will appear in the list with a *Not claimed yet* label.

## Bulk-generating coupons

- Navigate to the module configuration page
- Click the **Edit** button of the bulk-generated coupon pool to which you’d like to generate coupon codes
- Navigate to the **Coupons tab**
- Click the **Click here to start generation process** link in the infobox

![](https://cdn.document360.io/08a474ca-8fb4-4c3c-9cd8-665242086cd3/Images/Documentation/bulk_generation_coupons.png)

- Enter the **number of coupons** you’d like to generate

You can generate a maximum of 5 million coupons at a time to ensure that all coupons in the batch are generated without delays.

![](https://cdn.document360.io/08a474ca-8fb4-4c3c-9cd8-665242086cd3/Images/Documentation/bulk_generation.png)

- Click the **Start generation** button The coupon generation process will start immediately, and coupons will be populated on the page.

After the first coupon generation, you can generate further coupons by clicking the **Bulk generation** button at the top of the list.

## Settings

Under the Settings tab, you can find a checkbox to enable the**Auto redeem** functionality. This means that the [Coupon redeem event](https://developers.antavo.com/docs/api-events#coupon_redeem) does not have to be sent to set the coupon status to *redeemed*. Instead, if the coupon code is included in the [Checkout event](https://developers.antavo.com/docs/api-events#checkout), the [Coupon redeem event](https://developers.antavo.com/docs/api-events#coupon_redeem) is automatically registered.

![](https://cdn.document360.io/08a474ca-8fb4-4c3c-9cd8-665242086cd3/Images/Documentation/coupons-settings.png)

## Coupons

By navigating to the Coupons tab you can find the searchable and selectable list of coupons that have been uploaded or bulk-generated and/or assigned with the following information:

| **Code** | Coupon code |
| --- | --- |
| **Customer** | Assignee of the coupon |
| **Claimed at** | Date of the coupon assignment |
| **Expiration date Value** | Expiration date of the coupon |
| **Status** | - Unassigned: The coupon has been uploaded, but not claimed by a customer yet. - Claimed: The customer has spent points to get the coupon reward or it was assigned by a Management UI user [manually](/v1/docs/customer-insights#overview) or by a [workflow](/v1/docs/actions#reward-claim). - Redeemed: The customer has used the coupon at checkout. Please note that usage information is only available if the coupon was redeemed by a Management UI user manually or if the applied coupon code has been provided in the [Checkout event](https://developers.antavo.com/docs/api-events#checkout). A coupon that has been uploaded to a coupon pool can be [redeemed](https://developers.antavo.com/docs/api-events#coupon_redeem) without being assigned to a customer first. - Expired: The coupon has been claimed but expired without being used. - Invalid: The coupon has been invalidated by a Management UI user. |
| **Usages** | The number of times the coupon code has been used in a purchase |

![](https://cdn.document360.io/08a474ca-8fb4-4c3c-9cd8-665242086cd3/Images/Documentation/couponslist.png)

### Invalidate coupons

Please note that only coupons with *claimed* and*unassigned* statuses can be invalidated.

#### Invalidate one single coupon

This method is available only for coupons with *claimed* status.

- Click the hamburger button of the coupon code
- Click **Invalidate**
- Confirm the invalidation action

#### Invalidate multiple coupons at the same time

- Tick the checkbox of each coupon code you’d like to invalidate
- Click the blue I**nvalidate selected** button at the top of the page
- Confirm the invalidation action

The manual invalidation action updates the status of the coupon to *invalid*. If the coupon had been claimed and assigned to a customer, it triggers the registration of the `coupon_invalidate` [event](https://developers.antavo.com/docs/api-events#coupon_invalidate) in the event history of the assignee of the coupon.

### Unassign coupons

Please note that only *assigned* coupons can be unassigned.

#### Unassign one single coupon

- Click the hamburger button of the coupon code
- Click **Unassign**
- Confirm the unassign action

#### Unassign multiple coupons at the same time

- Tick the checkbox of each coupon code you’d like to unassign
- Click the blue **Unassign selected** button at the top of the page
- Confirm the unassign action

Coupons can also be unassigned using the `/v1/bulk-operation/coupons/{coupon_pool_id}/{action`} endpoint of the [Bulk Operations API](https://developers.antavo.com/reference/post_v1-bulk-operation-coupons-coupon-pool-id-action#/) by setting the `{action}` path parameter to `unassign`.

As a result of unassigning a coupon, the *Claimed at* date will be cleared for the coupon, and a `coupon_unassign` [event](https://developers.antavo.com/docs/api-events#/coupon_unassign) will be recorded in the customer's event history. Also, the number of claims for the coupon will be set to 0.

📓

Unassigning a coupon does not invalidate it. It simply removes the assignment from the current customer, allowing it to be assigned to another customer later.

### Transfer coupons

Please note that only coupons with *claimed* status can be transferred.

- Click the hamburger button of the coupon code
- Click **Transfer**
- Enter the ID of the customer who will receive the coupon in the **Target Customer ID** field, and/or enter the ID of the customer who will receive the coupon in the **Target Customer email** field
- Click **Transfer**

The manual transfer action triggers the registration of the `coupon_transfer` [event](https://developers.antavo.com/docs/api-events#coupon_transfer) in the event history of the previous assignee and the `coupon_receive` [event](https://developers.antavo.com/docs/internal-events#coupon_receive) in the event history of the new assignee.

### Redeem coupons

Please note that only coupons with *claimed* status can be redeemed.

To redeem a coupon manually:

- Tick the checkbox of each coupon code you’d like to redeem
- Click the blue **Redeem selected** button at the top of the page
- Confirm the redeem action

The manual redemption triggers the registration of the `coupon_redeem` [event](https://developers.antavo.com/docs/api-events#coupon_redeem) in the event history of the assignee and increments the number of coupon usage.

📓

Please note that uploaded coupons may be redeemed even before being claimed by sending a `coupon_redeem` [event](https://developers.antavo.com/docs/api-events#coupon_redeem) through the Events API. If the event is registered via API, the redeemed coupon gets assigned to the customer, the coupon code appears on the customer’s [Coupons page](/v1/docs/customer-insights#coupons) and the customer is added to the coupon on the pool’s [Coupons page](/v1/docs/coupons#coupons).

### 

### Unredeem coupons

Please note that only coupons with *redeemed* status can be unredeemed.

#### Unredeem one single coupon

- Click the hamburger button of the coupon code
- Click **Mark as unredeemed**
- Confirm the unredeem action

#### Unredeem multiple coupons at the same time

- Tick the checkbox of each coupon code you’d like to invalidate
- Click the blue **Unredeem selected** button at the top of the page
- Confirm the unredeem action

The unredeeem action updates the status of the coupon to *claimed*, triggers the registration of the `coupon_unredeem` [event](https://developers.antavo.com/docs/api-events#coupon_unredeem) in the event history of the assignee, and reduces the number of coupon usages.

## Managing coupon pools

### Editing a coupon pool

A coupon pool can be modified through the UI by following the steps below. Alternatively, the `/v1/coupon-pools/{coupon_pool_id}/update` endpoint of the [Coupon Pools API](https://developers.antavo.com/reference/post_v1-coupon-pools-coupon-pool-id-update#/) can be used to make changes.

- Go to the Coupons page
- Click on the**coupon pool** in the list that you want to edit
- **Edit** the coupon pool Please note that the source and pattern cannot be edited once *Save and generate* is clicked for bulk-generated coupons
- **Updating Coupons** This section allows you to update any property of the coupon pool and apply it to all, or a specific subset of coupons in the pool.
  - Update Criteria:
    - Do not update coupons: Only the coupons that are added from now on will inherit the new pool properties
    - Update unassigned coupons: Coupons created but not yet assigned to a customer will inherit the new pool properties.
    - Update not yet redeemed coupons: Coupons that are assigned but not yet redeemed will inherit the new pool properties.
    - Update all coupons: All coupons will inherit the coupon pool’s properties.
  - Matching
    - Select this option if you want to update only those coupons with a value field that matches the original number.

Don’t forget to save your changes by clicking **Save**.

### Deleting a coupon pool

It is important to note that once created, coupon pools cannot be deleted. If you no longer wish to use a specific coupon pool, ensure it is not selected in the configuration interface of loyalty program functionalities. This prevents the system from using the coupons from that pool.