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

# Coupons: Distribute and Track Unique Discount Codes

> Create Topic Coupons, import discount codes in bulk, assign unique codes to customers in a Flow, and track assignment and usage across your contacts.

The Coupons tool lets you store discount codes and assign one unique code to each customer through a Flow. Use it for new-customer offers, giveaways, or time-limited promotions. Every group of codes lives inside a **Topic Coupon**, which acts as a labeled container for all the codes belonging to a single promotion.

## Understanding Topic Coupons and Coupons

| Component        | Function                                                                  |
| ---------------- | ------------------------------------------------------------------------- |
| **Topic Coupon** | Groups codes that belong to the same promotion.                           |
| **Coupon**       | A specific code that has been imported and can be assigned to a customer. |
| **Status**       | Shows whether a Coupon has been assigned to a customer.                   |
| **Usage**        | Shows whether an assigned Coupon has been marked as used.                 |

You must create a Topic Coupon first, then import codes into it. The **Set up Coupon** Action in a Flow then assigns an available code from that Topic to the current customer.

## Create a Topic Coupon

<Steps>
  <Step title="Open Coupons">
    Select **Tools** from the left menu, then click the **Coupons** card.
  </Step>

  <Step title="Open the Topic Coupon tab">
    Select the **Topic Coupon** tab. The list shows each Topic's name, Coupon count, validity period, and Actions menu.
  </Step>

  <Step title="Click Create New">
    Click **+ Create New** to open the Topic Coupon creation dialog.
  </Step>

  <Step title="Enter topic information">
    Enter a **Name**, select a **Validity period** if the promotion expires, and add a **Description** if needed.
  </Step>

  <Step title="Save the topic">
    Click **Create** to save. If no validity period is selected, the column displays **Unlimited**.
  </Step>
</Steps>

To edit or archive a Topic Coupon later, open the three-dot menu in the **Actions** column and choose **Edit** or **Archive**. An archived Topic cannot assign new Coupons. Use the **Archive** tab to restore or delete Topics you no longer need.

## Import Codes into a Topic

### Prepare the Import File

Download the import template from the **Download import template** link in the import dialog. The CSV file uses a single column named `coupon`:

```
coupon
WELCOME10001
WELCOME10002
WELCOME10003
```

Each row must contain one unique code. Remove duplicate codes and empty rows before uploading.

### Import Codes

<Steps>
  <Step title="Open the Coupon tab">
    On the **Coupons** page, select the **Coupon** tab. This page includes Topic, Status, and Usage filters and a **Search code** field.
  </Step>

  <Step title="Click Import coupons">
    Click **Import coupons** to open the import dialog.
  </Step>

  <Step title="Select a Topic">
    In the **Topic** field, select the Topic Coupon that will receive the new codes.
  </Step>

  <Step title="Upload the CSV file">
    Select your prepared CSV file.
  </Step>

  <Step title="Confirm">
    Click **Confirm** to import the codes. After import, the Coupon table displays **Topic**, **Code**, **Status**, **Usage**, and **Created At** columns.
  </Step>
</Steps>

Use the **All topics**, **All statuses**, and **All usage** filters together with the **Search code** field to locate specific codes. Click **Download Coupon List** to export the list with its current statuses.

## Distribute Coupons in a Flow

### Add a Topic Coupon Action

<Steps>
  <Step title="Open Send Message">
    Create or open a **Send Message** block in Flow Builder.
  </Step>

  <Step title="Open Actions">
    Click **Create**, then select **Actions**.
  </Step>

  <Step title="Select Topic Coupon">
    Open the **Tools** group and select **Topic Coupon**.
  </Step>

  <Step title="Select a Type">
    In the **Type** field, choose the appropriate action:

    | Setting              | Function                                                                     |
    | -------------------- | ---------------------------------------------------------------------------- |
    | **Set up Coupon**    | Assigns an available Coupon from the selected Topic to the current customer. |
    | **Mark Coupon used** | Marks the customer's already-assigned Coupon as used.                        |
  </Step>

  <Step title="Select a Topic and continue">
    In the **Topic** field, select the Topic Coupon to use, then click **Continue** to add the Action to the block.
  </Step>
</Steps>

<Warning>
  Always run **Set up Coupon** before sending the Coupon field in a message. If no code has been assigned yet, ChatbotX cannot insert a value into the message.
</Warning>

### Send a Coupon Code in a Message

<Steps>
  <Step title="Add Send Text">
    Add or open **Send Text** content in the **Send Message** block.
  </Step>

  <Step title="Write the message">
    Enter the fixed message text, such as `Your discount code:`.
  </Step>

  <Step title="Insert the Coupon property">
    Click the `</>` icon in the editor. Under the **Coupons** group, select the Topic Coupon you want to insert. ChatbotX replaces this property at runtime with the code assigned to the customer.
  </Step>
</Steps>

### Check a Coupon with a Condition

Use a **Condition** node to branch the Flow based on a customer's Coupon status.

<Steps>
  <Step title="Open Add Condition">
    In the **Condition** node, click **Add Condition**.
  </Step>

  <Step title="Select a Topic Coupon field">
    In the field list, open the **Topic coupon** group and select the Topic you want to check.
  </Step>

  <Step title="Select an operator">
    Choose an operator based on what you need to check:

    | Operator          | Condition checked                                              |
    | ----------------- | -------------------------------------------------------------- |
    | **Has any value** | The customer has a Coupon assigned from this Topic.            |
    | **Used**          | The customer's Coupon from this Topic has been marked as used. |
    | **Is**            | The customer's Coupon matches a specific code value.           |
  </Step>

  <Step title="Set a comparison value and save">
    When using **Is**, select the comparison value in the third field, then click **Save**.
  </Step>
</Steps>

## Track Coupons by Customer

### Filter Contacts by Coupon

In **Contacts**, open the filter panel, click **Add Condition**, and select a Topic Coupon field. Choose **Has any value**, **Used**, or **Is** to generate the list you need. Click **Save** to apply the filter.

### View Coupons in Inbox

Open **Inbox**, select a customer's conversation, and expand the **Coupons** section in the contact profile on the right. Each Coupon card shows the Topic name, the assigned code, and the usage status. **Not used yet** means the code has not been marked as used.

## Example: Distribute a Welcome Coupon to New Customers

You have a Topic named `New Customer Welcome - 10% Off` with 30 imported codes (`WELCOME10001` to `WELCOME10030`). The Flow starts with an offer message and a **Get Coupon** button.

<Steps>
  <Step title="Customer clicks Get Coupon">
    The customer taps the button in your offer message.
  </Step>

  <Step title="Check for existing Coupon">
    A **Condition** node uses **Has any value** to check whether this customer already has a code from the Topic.
  </Step>

  <Step title="Send existing code if already assigned">
    If the condition matches, the Flow sends the customer's saved code again so they are not assigned a second one.
  </Step>

  <Step title="Assign a new code if none exists">
    If the condition does not match, the Flow runs **Set up Coupon** to assign a new code from the Topic.
  </Step>

  <Step title="Send the assigned code">
    The Flow sends a message containing the `Coupons > New Customer Welcome - 10% Off` property, which resolves to the customer's code.
  </Step>
</Steps>

<Note>
  A Topic Coupon in **Archive** cannot assign new codes. Confirm that your Topic is active and has enough available codes before starting a campaign.
</Note>