Coupon codes in Simio: per-contact promo code assignment

Import coupon codes by category, insert in message steps to send each contact a unique code, and track stock, expiry, and assignments.

Simio stores pools of coupon codes grouped by category and gives each contact a unique code when a message containing {{coupon_code}} is sent. This page explains how to import codes, use them in campaigns, automations, and chatbots, monitor stock, and understand how codes are assigned and expire.

How coupon codes work

• Category: a label shared by a pool of codes, for example summer_sale. A category is created the first time you import codes into it. There is no separate screen to create one, and it disappears from the list once all its codes are deleted.
• Assignment: when Simio prepares a message for a contact, it takes an available code from the selected category and assigns it to that contact. The code is then marked Used.
• One code per contact and category: a contact keeps the same code for a category across every message, campaign, automation, and chatbot, as long as that code has not expired. A contact can hold one code in each category at the same time.

“Used” means “assigned to a contact”. Simio does not know whether the customer actually redeemed the code in your store or on your website.

Import codes

You manage coupon codes in Settings > Messages > Coupon codes.

1. Open the import panel

   Click Import codes.

2. Enter a category

   Type the category name. It must start with a letter, contain only lowercase letters, digits, and underscores, and be 50 characters or fewer (for example summer_sale). To add codes to an existing category, enter its exact name.

3. Add your codes

   Either drop a CSV file in CSV file, or paste codes in Or paste codes directly. See the formats below.

4. Import

   Click Import. File imports run in the background, and a notification tells you when the import is completed or has failed.

Importing always adds codes. It never removes or changes existing codes in the category. To start over, delete codes first (see Export and delete codes).

CSV file format

The file must have a header row with a code column.

Column	Required	Content
code	Yes	The coupon code
expired_at	No	Expiry date, format YYYY-MM-DD
category	No	Category for this row. If empty, the category entered in the form is used

coupons.csv

code,expired_at
WELCOME-4H7P2,
WELCOME-9KD31,2026-06-30

Limits and requirements:

• Up to 100,000 codes and 10 MB per file
• UTF-8 encoding
• .csv or .txt extension
• Comma (,) separator only

A file without a code header, or a file separated by semicolons (;, common in Excel exports with French settings), imports no codes, and no error message is shown. An expired_at value in the wrong format is ignored, and the code is imported without an expiry date.

Pasted codes format

When pasting codes, don’t add a header. Enter one code per line, optionally followed by an expiry date separated by a comma or a semicolon:

WELCOME-4H7P2
WELCOME-9KD31,2026-06-30
WELCOME-X2M8Q;2026-12-31

A line with a badly formatted date is skipped.

Duplicate codes

A code that already exists in the same category is skipped. The comparison is case-sensitive and ignores leading and trailing spaces. The same code can exist in two different categories.

Duplicates within a single import (the same code twice in your file or pasted text) are not detected and are imported twice, so the same code could be sent to two contacts. Remove duplicates from your list before importing.

Use coupon codes in messages

Coupon codes work in Message steps (free text) of campaigns, automations, and chatbots.

1. Insert the variable

   In the Message step, under Body, pick coupon_code in Select a variable and click Insert. This adds {{coupon_code}} at the cursor position. You can also type {{coupon_code}} directly.

2. Choose a category

   As soon as the body contains {{coupon_code}}, a - category selector appears under the body. Pick the category to draw codes from. Each option shows the number of available codes, for example summer_sale (1240 available).

A code is assigned only when the body contains exactly {{coupon_code}} and a category is selected. You can only select a category that already has at least one imported code.

{{coupon_code}} has no default value. If the category has no valid code left when the message is sent, the message is still sent and {{coupon_code}} is replaced with an empty string. Keep an eye on your stock (see Monitor stock).

WhatsApp templates (including the initial template step of a campaign, {{1}}, {{2}} variables, and copy-code buttons) don’t draw from coupon stock. Use a Message step to send a coupon code.

When a contact gets a new code

Simio assigns a new code from the category only if:

• the contact has never received a code from this category, or
• the contact’s current code for this category has expired.

Otherwise, the contact receives the code already assigned to them. The assigned code is visible on the contact’s profile.

If a message fails after the code was assigned, the code stays Used and assigned to that contact, who receives it again in the next message using this category.

Manage a category

The category list shows, for each category, the number of codes left and its total, used, and expired counts. Select a category to see:

• Counters: Total, Available, Used, and Expired
• Code table: Code, Status, Assigned to, Used at, and Expires. Use the search field to find a code, filter by status, and click the refresh button to reload the list.

Code statuses

Status	Meaning
Available	In stock, not assigned, can be assigned when a message is sent
Used	Assigned to a contact. Used at is the assignment date
Expired	Not assigned and past its expiry date. Removed from stock

A Used code never changes to Expired, even after its expiry date. Only available codes become expired.

Expiry dates

Expiry dates are in UTC, and a code stops being valid at 00:00 UTC on the date entered, not at the end of that day.

To keep a code valid until December 31 inclusive, enter 2027-01-01 as the expiry date. With 2026-12-31, the code stops being sent on December 31 at 00:00 UTC.

When a message is sent, Simio checks expiry in real time, so expired codes are never assigned. A daily job at 01:00 UTC updates their status to Expired in the table. Between midnight and that update, an expired code can still appear as Available, but it is no longer sent.

Monitor stock

Simio does not send notifications or emails about coupon stock. Use these signals:

• Low badge: shown in the category list and on the category detail (Low stock) when available codes are less than 20% of the category’s total. The threshold is fixed. Because the total includes used and expired codes, a category with many expired codes can show Low even after few sends.
• Empty coupon codes on the home dashboard: lists categories that are selected in at least one Message step and have no available code left. Click Add codes to open the coupon codes settings and import more. This alert only appears at zero, not at the Low threshold. See Analytics.

Export and delete codes

From a category’s detail, use these actions:

• Export: downloads <category>_coupons.csv with all codes in the category, whatever their status, newest first. The file uses a semicolon (;) separator and UTF-8 encoding.
• Delete unused: deletes Available codes only.
• Delete all: deletes Available and Expired codes.

Export column	Content
code	The code
category	The category
status	available, used, or expired
contact_phone	Contact’s phone number, if assigned
contact_name	Contact’s first and last name, if assigned
used_at	Assignment date and time, ISO 8601 UTC
expired_at	Expiry date, ISO 8601 UTC

Neither delete action removes Used codes. Contacts keep their assigned code, which stays visible on their profile and in exports and continues to be sent until it expires.

Because the export uses semicolons and file imports only accept commas, you can’t re-import an exported file as is.

Target contacts by coupon

In segments, the Coupon filter selects contacts for one category:

• has active coupon: the contact has an assigned code in this category that has no expiry date or expires in the future.
• has no active coupon: the contact never received a code in this category, or their code has expired.

“Active” means assigned and not expired, not redeemed. See Contacts and segments.