# How dynamic coupons work

> What a dynamic coupon list is, how a merge tag hands each recipient a different code, what happens when a list runs out, and how uploaded lists differ from Shopify coupons that Releva creates for you.

A dynamic coupon list is a pool of one-time discount codes that Releva hands out one per recipient. You put the list’s merge tag into a message; at send time each recipient gets a code of their own. Lists live under **Data Platform › Dynamic Coupons**.

## Uploaded lists and Shopify coupons

There are two ways to fill a list with codes. Both use the same merge tag, and each recipient gets one code either way.

|                       | Uploaded list                                                                                         | Shopify coupon                                                                                                                 |
| --------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Who creates the codes | You, in your shop. You export them to a `.txt` file and upload it.                                    | Releva, in your Shopify store, from the discount you set in Releva.                                                            |
| Discount settings     | Kept in your shop. Releva only knows the codes.                                                       | Set in Releva: type and value, what it applies to, minimum purchase, combinations and active dates. You can change them later. |
| Keeping it stocked    | You upload more codes before the list runs out.                                                       | Releva keeps about 1,000 unused codes ready and creates more when fewer than 500 are left.                                     |
| Available on          | Every shop.                                                                                           | Shopify shops connected through the Releva app.                                                                                |
| Guides                | [Upload a list of coupon codes](https://releva.ai/documentation/guides/dynamic-coupons/upload-a-list-of-coupon-codes/) | [Create Shopify coupons](https://releva.ai/documentation/guides/dynamic-coupons/create-shopify-coupons/)                                        |

On a Shopify shop, **Dynamic Coupons** has two tabs: **Shopify Coupons** and **Uploaded Coupons**. On every other shop the page lists uploaded lists only and the button reads **New coupon**. Shopify coupons need the Releva app’s permission to create discounts in Shopify; see [Re-authorize Releva in Shopify](https://releva.ai/documentation/guides/dynamic-coupons/re-authorize-releva-in-shopify/).

## The merge tag

Every list has a name made of letters, numbers and underscores. Its merge tag is:

```plaintext
{{dynamicCoupons.<name>}}
```

For a list named `DEMO_WELCOME_10` the tag is `{{dynamicCoupons.DEMO_WELCOME_10}}`. In the message editors the **Merge Tags** picker lists each list as **Dynamic coupon:** followed by the name turned into words: underscores become spaces and each word is capitalised, so `welcome_10` is listed as **Dynamic coupon: Welcome 10**. A capital letter inside the name also starts a new word, so an all-caps name such as `DEMO_WELCOME_10` is listed with a space between the letters (**Dynamic coupon: D E M O W E L C O M E 10**). The picker only offers lists that have at least one unused code. Where you find it in each channel:

* **Emails** in the visual editor: select a text block, open **Merge tags** in the text toolbar and pick the entry; it is inserted for you. See [Build an email in the visual editor](https://releva.ai/documentation/guides/emails/build-an-email-in-the-visual-editor/).
* **Web** and **mobile app push notifications**: select **Merge Tags** next to **Subject** and copy the entry’s pattern into **Body**. See [Create a web push notification](https://releva.ai/documentation/guides/push-notifications/create-a-web-push-notification/) and [Create a mobile app push notification](https://releva.ai/documentation/guides/push-notifications/create-a-mobile-app-push-notification/).
* **SMS**: select **Merge Tags** and copy the pattern into the message. See [Create an SMS](https://releva.ai/documentation/guides/sms/create-an-sms/).
* **Viber**, in **Text** and **Multimedia** mode: select **Merge Tags** and copy the pattern into **Message**. See [Create a Viber message](https://releva.ai/documentation/guides/viber/create-a-viber-message/).

The tag works in emails, push notifications, text messages, Viber messages, WhatsApp messages and webhooks. You can use the same list more than once in one message; the recipient gets the same code in every place. Send yourself a test message to see the tag replaced by a real code before you use it in a campaign or workflow.

## What happens at send time

1. Releva reads the merge tags in the message and looks up each list by name.
2. For each recipient it claims one unused code per list. A claimed code is marked as sent and is never handed out again. Claims are safe when several sends run at once: two recipients never get the same code.
3. The code is written into the message in place of the tag.

Two things follow from this:

* **A list can run out.** If fewer unused codes are left than there are recipients, the recipients who did not get a code are **skipped**: the message is not sent to them at all, with no partial message. Releva logs a warning but does not notify you. Check **Remaining** on the list’s card before large sends and [add codes](https://releva.ai/documentation/guides/dynamic-coupons/add-codes-to-a-coupon-list/) in time.
* **A missing list skips everyone.** If a tag names a list that does not exist (deleted, or renamed), no recipient gets a code, so the message is not sent to anyone. Fix the tag or recreate the list under the old name.

Shopify coupons rarely run out. When a send needs more codes than the pool has, Releva tries for up to about 30 seconds to create the missing codes in Shopify first, and it schedules a refill whenever fewer than 500 unused codes are left. For a send to many thousands of recipients, [add codes](https://releva.ai/documentation/guides/dynamic-coupons/add-codes-to-a-shopify-coupon/) in advance.

## Uploading and importing

This section is about uploaded lists. An upload does not add codes immediately. **Save** stores the file and queues an import that reads it line by line, skips empty lines, drops duplicates and adds the codes as unused. Until the import finishes the list’s card shows **Remaining: 0** and the merge tag picker does not offer the list. When it finishes you get an e-mail with the subject **Your dynamic coupons import has been processed successfully!** and the number of unused codes now in the list.

Uploading a second file to an existing list adds its codes. A code that is already in the list is not added twice. If it had already been sent, the import marks it as unused again, so only upload new codes.

The **Sample** card on a list’s page shows up to 10 random unused codes, so you can check that the right codes were imported. The **Remaining** count is the number of unused codes, not the number uploaded.

## Renaming and deleting

* The name is the merge tag. Renaming a list or a Shopify coupon breaks every message that uses the old tag. An uploaded list cannot be renamed on its own anyway: saving without a file answers **No file uploaded.**
* Deleting a list removes all its codes, sent or not, and its merge tag. Messages that still use the tag are skipped for every recipient. See [Delete a coupon list](https://releva.ai/documentation/guides/dynamic-coupons/delete-a-coupon-list/) and [Delete a Shopify coupon](https://releva.ai/documentation/guides/dynamic-coupons/delete-a-shopify-coupon/).
* The codes themselves live in your shop. Deleting an uploaded list does not delete its codes from your shop. Deleting a Shopify coupon removes its unsent codes from Shopify; codes already sent stay usable.

## Shopify coupons

Releva creates each code as its own discount in your Shopify store, named after the code and limited to one use. A code is the optional prefix you choose followed by 8 random letters and numbers. The pool starts with about 1,000 codes, created in batches right after you save. On the **Shopify Coupons** tab each coupon’s row shows **Available/Total** and a **Status** of **Generating**, **Live** or **Error**; its menu offers **Add Codes**, **View History** and **Delete**. A **Low stock: N left** badge next to the status means that creating codes failed or that the pool is empty, so it can read **Low stock: 300 left** next to **Error**, and a new coupon briefly shows **Low stock: 0 left** next to **Generating**.

* **Active dates per code.** With activation **At send time**, a code becomes valid when it is sent. Expiration **After 1 year** or **After a certain number of days/hours** counts from that moment, so every recipient gets the same amount of time. A fixed expiration date ends all codes at once, and Releva stops creating codes after it.
* **Changing the discount.** Saving new discount settings ends the current version: Releva removes the unsent codes from Shopify and creates new ones. Codes already sent keep their old discount. **View History** lists every version with its dates and how many codes were sent under it. See [Change a Shopify coupon](https://releva.ai/documentation/guides/dynamic-coupons/change-a-shopify-coupon/).
* **Other platforms.** Today only the Shopify integration creates codes. A platform partner whose integration adds the same support gets the same tab, named after the platform, or **Generated Coupons** on a custom platform; its buttons read **Create Generated Coupon** in that case.
* **Permission.** If the Releva app loses its permission to manage discounts in Shopify, Releva cannot create codes and the coupon shows **Error**. Re-authorize the app and Releva continues; see [Re-authorize Releva in Shopify](https://releva.ai/documentation/guides/dynamic-coupons/re-authorize-releva-in-shopify/).

## Next steps

* [Upload a list of coupon codes](https://releva.ai/documentation/guides/dynamic-coupons/upload-a-list-of-coupon-codes/): Create a coupon list from a .txt file of codes that already exist in your shop.
* [Check how many coupon codes are left](https://releva.ai/documentation/guides/dynamic-coupons/check-how-many-coupon-codes-are-left/): See how many unused codes a list still has.
* [Add codes to a coupon list](https://releva.ai/documentation/guides/dynamic-coupons/add-codes-to-a-coupon-list/): Top up a list by uploading another file of codes.
* [Delete a coupon list](https://releva.ai/documentation/guides/dynamic-coupons/delete-a-coupon-list/): Remove a list and all its codes when you no longer need it.
* [Create Shopify coupons](https://releva.ai/documentation/guides/dynamic-coupons/create-shopify-coupons/): On a Shopify shop, let Releva create the codes for you instead of uploading them.