# Coupons API > Créez des coupons et gérez leurs réserves de codes uniques pour vos e-mails. URL de base : `https://api.emailit.com/v2`. Authentifiez-vous avec `Authorization: Bearer `. ## Créer un coupon — POST /coupons > Créez un coupon avec une réserve de codes uniques, ou un code partagé, pour vos e-mails. Alpha : réservé à l’équipe Emailit. # Créer un coupon Crée un coupon. Insérez-le dans un e-mail avec `{{coupon "key"}}` : au rendu de l’e-mail, chaque destinataire reçoit un code. Nécessite une clé API avec la portée `full`. > **Commerce est en alpha:** Commerce est réservé à l’équipe Emailit pendant que nous le testons. Les autres requêtes renvoient `403` avec `error: "commerce_alpha"`. Les clés API ne fonctionnent que dans les espaces de travail qui appartiennent à l’équipe Emailit. Consultez [Qui peut utiliser Commerce](/fr/docs/commerce/#who-can-use-commerce). - Un coupon **à codes uniques** contient une réserve de codes à usage unique. Chaque destinataire se voit attribuer le plus ancien code libre, un par campagne ou par automatisation, et reçoit de nouveau le même code chaque fois que cet e-mail est rendu pour lui. Importez les codes de votre boutique ici ou avec [Ajouter des codes à un coupon](/fr/docs/api-reference/coupons/add-codes/), ou générez des codes dans Emailit et importez-les dans votre boutique. - Un coupon **à code fixe** a un seul code, `static_code`, pour tout le monde. Quand une [commande](/fr/docs/api-reference/orders/create/) indique un code dans `coupon_codes`, le code est marqué comme utilisé. Consultez [Produits, coupons et panier](/fr/docs/campaigns/products-and-coupons/#coupon-codes). `POST /coupons` ## Corps de la requête - `key` (string, obligatoire): Le nom que vous utilisez dans le contenu, unique dans l’espace de travail. De 1 à 64 lettres minuscules, chiffres, `-` ou `_`, en commençant par une lettre ou un chiffre. Les majuscules sont converties en minuscules. - `name` (string, obligatoire): Nom du coupon affiché dans le tableau de bord, 191 caractères au maximum. - `description` (string | null): Note pour votre équipe. Un texte plus long est coupé à 1 000 caractères. - `kind` (string): `unique` (par défaut) ou `static`. - `static_code` (string | null): 191 caractères au maximum. Obligatoire pour un coupon à code fixe : le code que tout le monde reçoit. Pour un coupon à codes uniques, le texte que reçoivent les destinataires quand la réserve est vide ou que le coupon a expiré. Sans lui, ils reçoivent une chaîne vide. - `discount_label` (string | null): Courte description de la réduction, comme `10% off`. Un texte plus long est coupé à 191 caractères. - `expires_at` (string | null): Date-heure ISO 8601. Passé cette date, les destinataires d’un coupon à codes uniques reçoivent `static_code` au lieu d’un code, y compris dans les e-mails rendus de nouveau. Emailit n’applique pas l’expiration dans votre boutique. - `codes` (string[] | string): Codes à ajouter à la réserve : un tableau, ou un texte avec un code par ligne. Pour un texte CSV, la première colonne est lue et un en-tête comme `code` ou `coupon_code` est ignoré. Un code compte de 2 à 64 lettres, chiffres, `-`, `_` ou `.`, et commence par une lettre ou un chiffre. Les codes non valides sont écartés et les doublons ne sont ajoutés qu’une fois. 10 000 codes au maximum. ## Réponse Renvoie `201 Created` avec l’[objet coupon](/fr/docs/api-reference/coupons/get/). Renvoie `422` quand un champ n’est pas valide ou qu’un autre coupon a déjà cette clé. **Requête** `POST /coupons` **cURL** ```bash curl -X POST https://api.emailit.com/v2/coupons \ -H "Authorization: Bearer your_api_key" \ -H "Content-Type: application/json" \ -d '{ "key": "welcome-10", "name": "Welcome 10% off", "description": "First-order discount for new subscribers.", "kind": "unique", "static_code": "WELCOME10", "discount_label": "10% off", "expires_at": "2026-12-31T23:59:59Z", "codes": ["WELCOME-7KQ2M9XA", "WELCOME-H4TZ8RCN", "WELCOME-P2WD6YFE"] }' ``` **201** ```json { "object": "coupon", "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ", "key": "welcome-10", "name": "Welcome 10% off", "description": "First-order discount for new subscribers.", "kind": "unique", "static_code": "WELCOME10", "discount_label": "10% off", "expires_at": "2026-12-31T23:59:59.000Z", "codes_total": 3, "codes_available": 3, "codes_assigned": 0, "codes_redeemed": 0, "created_at": "2026-10-01T09:00:12.304Z", "updated_at": "2026-10-01T09:00:12.304Z" } ``` **422** ```json { "message": "Validation failed. key: A coupon with this key already exists.", "errors": { "key": [ "A coupon with this key already exists." ] } } ``` --- Source: https://emailit.com/fr/docs/api-reference/coupons/create/ ## Récupérer un coupon — GET /coupons/{id} > Récupérez un coupon par son ID ou sa clé, avec le nombre de ses codes disponibles, attribués et utilisés. Alpha : réservé à l’équipe Emailit. # Récupérer un coupon Récupère un coupon par son ID ou sa clé, avec le nombre de ses codes. Nécessite une clé API avec la portée `full`. > **Commerce est en alpha:** Commerce est réservé à l’équipe Emailit pendant que nous le testons. Les autres requêtes renvoient `403` avec `error: "commerce_alpha"`. Les clés API ne fonctionnent que dans les espaces de travail qui appartiennent à l’équipe Emailit. Consultez [Qui peut utiliser Commerce](/fr/docs/commerce/#who-can-use-commerce). `GET /coupons/{id}` ## Paramètres de chemin - `id` (string, obligatoire): L’ID du coupon (`cpn_...`) ou la `key` du coupon. ## L’objet coupon - `object` (string): Toujours `coupon`. - `id` (string): ID du coupon (`cpn_...`). - `key` (string): Le nom que vous utilisez dans le contenu des e-mails : `{{coupon "welcome-10"}}`. Consultez [Produits, coupons et panier](/fr/docs/campaigns/products-and-coupons/#coupon-codes). - `name` (string): Nom du coupon affiché dans le tableau de bord. - `description` (string | null): Note pour votre équipe. - `kind` (string): - `unique` : une réserve de codes à usage unique. Chaque destinataire reçoit son propre code, un par campagne ou par automatisation, et de nouveau le même code quand l’e-mail est rendu de nouveau. - `static` : un seul code, `static_code`, pour tout le monde. - `static_code` (string | null): Le code partagé d’un coupon à code fixe. Pour un coupon à codes uniques, le texte que reçoivent les destinataires quand il ne reste aucun code ou que le coupon a expiré. Sans lui, ils reçoivent une chaîne vide. - `discount_label` (string | null): Courte description de la réduction, comme `10% off`. - `expires_at` (string | null): Passé cette date, les destinataires d’un coupon à codes uniques reçoivent `static_code` au lieu d’un code. - `codes_total` (integer): Codes dans la réserve. - `codes_available` (integer): Codes qui peuvent encore être distribués : non attribués à un contact et non utilisés dans une commande. - `codes_assigned` (integer): Codes attribués à un contact, y compris ceux déjà utilisés. - `codes_redeemed` (integer): Codes utilisés dans une [commande](/fr/docs/api-reference/orders/create/) (`coupon_codes`). - `created_at, updated_at` (string): Dates de création et de dernière modification du coupon, au format ISO 8601 UTC. **Requête** `GET /coupons/{id}` **cURL** ```bash curl https://api.emailit.com/v2/coupons/welcome-10 \ -H "Authorization: Bearer your_api_key" ``` **200** ```json { "object": "coupon", "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ", "key": "welcome-10", "name": "Welcome 10% off", "description": "First-order discount for new subscribers.", "kind": "unique", "static_code": "WELCOME10", "discount_label": "10% off", "expires_at": "2026-12-31T23:59:59.000Z", "codes_total": 5000, "codes_available": 3812, "codes_assigned": 1188, "codes_redeemed": 143, "created_at": "2026-10-01T09:00:12.304Z", "updated_at": "2026-10-01T09:00:12.304Z" } ``` **404** ```json { "error": "Coupon not found", "message": "Coupon not found." } ``` --- Source: https://emailit.com/fr/docs/api-reference/coupons/get/ ## Mettre à jour un coupon — POST /coupons/{id} > Modifiez la clé, le nom, le type, le code de secours ou fixe, le libellé ou l’expiration d’un coupon. Alpha : réservé à l’équipe Emailit. # Mettre à jour un coupon Met à jour un coupon. Seuls les champs envoyés changent. Pour ajouter des codes, utilisez [Ajouter des codes à un coupon](/fr/docs/api-reference/coupons/add-codes/) : `codes` est ignoré dans cette requête. Nécessite une clé API avec la portée `full`. > **Commerce est en alpha:** Commerce est réservé à l’équipe Emailit pendant que nous le testons. Les autres requêtes renvoient `403` avec `error: "commerce_alpha"`. Les clés API ne fonctionnent que dans les espaces de travail qui appartiennent à l’équipe Emailit. Consultez [Qui peut utiliser Commerce](/fr/docs/commerce/#who-can-use-commerce). Si vous modifiez la `key`, mettez aussi à jour les balises `{{coupon "key"}}` de vos e-mails : Emailit recherche les coupons par la clé indiquée dans le contenu. `POST /coupons/{id}` ## Paramètres de chemin - `id` (string, obligatoire): L’ID du coupon (`cpn_...`) ou la `key` actuelle du coupon. ## Corps de la requête N’importe lequel des champs `key`, `name`, `description`, `kind`, `static_code`, `discount_label` et `expires_at`, avec les règles de [Créer un coupon](/fr/docs/api-reference/coupons/create/). Envoyez `null` pour `description`, `static_code`, `discount_label` ou `expires_at` pour effacer le champ. Un coupon qui est ou devient `static` doit garder un `static_code`. ## Réponse Renvoie `200 OK` avec l’[objet coupon](/fr/docs/api-reference/coupons/get/) mis à jour. Renvoie `404` si aucun coupon ne correspond à `id` et `422` quand un champ n’est pas valide ou que la nouvelle clé est déjà prise. **Requête** `POST /coupons/{id}` **cURL** ```bash curl -X POST https://api.emailit.com/v2/coupons/welcome-10 \ -H "Authorization: Bearer your_api_key" \ -H "Content-Type: application/json" \ -d '{ "expires_at": "2027-01-31T23:59:59Z" }' ``` **200** ```json { "object": "coupon", "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ", "key": "welcome-10", "name": "Welcome 10% off", "description": "First-order discount for new subscribers.", "kind": "unique", "static_code": "WELCOME10", "discount_label": "10% off", "expires_at": "2027-01-31T23:59:59.000Z", "codes_total": 5000, "codes_available": 3812, "codes_assigned": 1188, "codes_redeemed": 143, "created_at": "2026-10-01T09:00:12.304Z", "updated_at": "2026-10-09T15:47:20.061Z" } ``` **404** ```json { "error": "Coupon not found", "message": "Coupon not found." } ``` **422** ```json { "message": "Validation failed. static_code: A static coupon needs its code.", "errors": { "static_code": [ "A static coupon needs its code." ] } } ``` --- Source: https://emailit.com/fr/docs/api-reference/coupons/update/ ## Lister les coupons — GET /coupons > Listez les coupons de votre espace de travail, du plus récent au plus ancien, avec le nombre de leurs codes. Alpha : réservé à l’équipe Emailit. # Lister les coupons Liste les coupons de votre espace de travail, du plus récent au plus ancien, avec le nombre de leurs codes. Nécessite une clé API avec la portée `full`. > **Commerce est en alpha:** Commerce est réservé à l’équipe Emailit pendant que nous le testons. Les autres requêtes renvoient `403` avec `error: "commerce_alpha"`. Les clés API ne fonctionnent que dans les espaces de travail qui appartiennent à l’équipe Emailit. Consultez [Qui peut utiliser Commerce](/fr/docs/commerce/#who-can-use-commerce). `GET /coupons` ## Paramètres de requête - `page` (integer): Numéro de page pour la pagination (minimum : 1, par défaut : 1). - `limit` (integer): Nombre de coupons à renvoyer (minimum : 1, maximum : 100, par défaut : 25). - `search` (string): Correspondance insensible à la casse sur le nom ou la clé du coupon. - `match`, `order`, `direction`: voir [Filtrage et tri](https://emailit.com/fr/docs/api-reference/filtering/). ## Filtres et tri Clés de filtre et de tri : voir [Filtrage et tri](https://emailit.com/fr/docs/api-reference/filtering/). ## Réponse Renvoie une page d’[objets coupon](/fr/docs/api-reference/coupons/get/) dans `data`, avec `total_records`, `next_page_url` et `previous_page_url`. Les URL de page ne contiennent que `page` et `limit` : ajoutez de nouveau votre recherche et vos filtres quand vous les suivez. **Requête** `GET /coupons` **cURL** ```bash curl "https://api.emailit.com/v2/coupons?kind.exact=unique" \ -H "Authorization: Bearer your_api_key" ``` **200** ```json { "data": [ { "object": "coupon", "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ", "key": "welcome-10", "name": "Welcome 10% off", "description": "First-order discount for new subscribers.", "kind": "unique", "static_code": "WELCOME10", "discount_label": "10% off", "expires_at": "2026-12-31T23:59:59.000Z", "codes_total": 5000, "codes_available": 3812, "codes_assigned": 1188, "codes_redeemed": 143, "created_at": "2026-10-01T09:00:12.304Z", "updated_at": "2026-10-01T09:00:12.304Z" } ], "total_records": 1, "next_page_url": null, "previous_page_url": null } ``` --- Source: https://emailit.com/fr/docs/api-reference/coupons/list/ ## Supprimer un coupon — DELETE /coupons/{id} > Supprimez un coupon et tous ses codes. Alpha : réservé à l’équipe Emailit. # Supprimer un coupon Supprime un coupon avec tous ses codes, y compris ceux qui sont attribués et utilisés. Les commandes gardent les codes dans leur `coupon_codes`. Nécessite une clé API avec la portée `full`. > **Commerce est en alpha:** Commerce est réservé à l’équipe Emailit pendant que nous le testons. Les autres requêtes renvoient `403` avec `error: "commerce_alpha"`. Les clés API ne fonctionnent que dans les espaces de travail qui appartiennent à l’équipe Emailit. Consultez [Qui peut utiliser Commerce](/fr/docs/commerce/#who-can-use-commerce). `DELETE /coupons/{id}` ## Paramètres de chemin - `id` (string, obligatoire): L’ID du coupon (`cpn_...`) ou la `key` du coupon. **Requête** `DELETE /coupons/{id}` **cURL** ```bash curl -X DELETE https://api.emailit.com/v2/coupons/cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ \ -H "Authorization: Bearer your_api_key" ``` **200** ```json { "object": "coupon", "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ", "deleted": true } ``` **404** ```json { "error": "Coupon not found", "message": "Coupon not found." } ``` --- Source: https://emailit.com/fr/docs/api-reference/coupons/delete/ ## Lister les codes d’un coupon — GET /coupons/{id}/codes > Listez les codes d’un coupon avec le contact auquel ils ont été attribués et s’ils ont été utilisés, en JSON ou en export CSV. Alpha : réservé à l’équipe Emailit. # Lister les codes d’un coupon Liste les codes d’un coupon, du plus ancien au plus récent : l’ordre dans lequel ils sont distribués. Utilisez `format=csv` pour les exporter, par exemple pour importer des codes générés dans votre boutique. Nécessite une clé API avec la portée `full`. > **Commerce est en alpha:** Commerce est réservé à l’équipe Emailit pendant que nous le testons. Les autres requêtes renvoient `403` avec `error: "commerce_alpha"`. Les clés API ne fonctionnent que dans les espaces de travail qui appartiennent à l’équipe Emailit. Consultez [Qui peut utiliser Commerce](/fr/docs/commerce/#who-can-use-commerce). `GET /coupons/{id}/codes` ## Paramètres de chemin - `id` (string, obligatoire): L’ID du coupon (`cpn_...`) ou la `key` du coupon. ## Paramètres de requête - `page` (integer): Numéro de page pour la pagination (minimum : 1, par défaut : 1). - `limit` (integer): Nombre de codes à renvoyer (minimum : 1, maximum : 100, par défaut : 50). - `status` (string): - `available` : non attribué à un contact et non utilisé dans une commande ; il peut donc encore être distribué. - `assigned` : attribué à un contact et non utilisé. - `redeemed` : utilisé dans une commande. - `format` (string): `json` (par défaut) ou `csv`. Le CSV renvoie dans un seul fichier, sans pagination, tous les codes qui correspondent à `status`, avec les colonnes `code`, `status`, `email`, `assigned_at` et `redeemed_at`. Les filtres `key.condition` et le tri ne s’appliquent pas au CSV. - `match`, `order`, `direction`: voir [Filtrage et tri](https://emailit.com/fr/docs/api-reference/filtering/). ## Filtres et tri Clés de filtre et de tri : voir [Filtrage et tri](https://emailit.com/fr/docs/api-reference/filtering/). ## Réponse Renvoie une page de codes de coupon dans `data`, avec `total_records`, `next_page_url` et `previous_page_url`. Chaque code a : - `object` (string): Toujours `coupon_code`. - `id` (string): ID du code (`cpc_...`). - `code` (string): Le code. - `contact_id, email` (string | null): Le contact auquel le code est attribué, ou `null`. - `source_id` (string | null): La campagne (`cmp_...`) ou l’automatisation (`aut_...`) dont l’e-mail a reçu le code. - `assigned_at` (string | null): Date d’attribution du code. - `redeemed_at, redeemed_order_id` (string | null): Date à laquelle le code a été utilisé, et commande qui l’a utilisé (`ord_...`). - `created_at` (string): Date d’ajout du code à la réserve. **Requête** `GET /coupons/{id}/codes` **cURL** ```bash curl "https://api.emailit.com/v2/coupons/welcome-10/codes?status=assigned&limit=2" \ -H "Authorization: Bearer your_api_key" ``` **200** ```json { "data": [ { "object": "coupon_code", "id": "cpc_3s6oCjlRbLFujYObEAcuiZmGKqu", "code": "WELCOME-H4TZ8RCN", "contact_id": "con_3MjLVacsYA6keJucAbOs3o3XhyA", "email": "grace@example.com", "source_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN", "assigned_at": "2026-10-08T09:00:41.773Z", "redeemed_at": null, "redeemed_order_id": null, "created_at": "2026-10-01T09:00:12.304Z" }, { "object": "coupon_code", "id": "cpc_3u9TrZTopqOgaqT9FcZFareUFGj", "code": "WELCOME-P2WD6YFE", "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs", "email": "ada@example.com", "source_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN", "assigned_at": "2026-10-08T09:00:41.802Z", "redeemed_at": null, "redeemed_order_id": null, "created_at": "2026-10-01T09:00:12.304Z" } ], "total_records": 1045, "next_page_url": "/v2/coupons/cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ/codes?page=2&limit=2", "previous_page_url": null } ``` **CSV** ```text code,status,email,assigned_at,redeemed_at WELCOME-7KQ2M9XA,redeemed,ada@example.com,2026-10-08T09:00:41.751Z,2026-10-08T14:32:10.000Z WELCOME-H4TZ8RCN,assigned,grace@example.com,2026-10-08T09:00:41.773Z, WELCOME-QX3B9NMV,available,,, ``` **404** ```json { "error": "Coupon not found", "message": "Coupon not found." } ``` --- Source: https://emailit.com/fr/docs/api-reference/coupons/list-codes/ ## Ajouter des codes à un coupon — POST /coupons/{id}/codes > Importez les codes de votre boutique dans un coupon à codes uniques, ou générez des codes aléatoires dans Emailit. Alpha : réservé à l’équipe Emailit. # Ajouter des codes à un coupon Ajoute des codes à la réserve d’un coupon à codes uniques. Importez avec `codes` des codes qui existent dans votre boutique, ou laissez Emailit créer des codes aléatoires avec `generate`, puis importez-les dans votre boutique avec [Lister les codes d’un coupon](/fr/docs/api-reference/coupons/list-codes/) (`format=csv`). Les codes déjà présents dans la réserve sont ignorés. Les coupons à code fixe ont un seul code et renvoient `422`. Nécessite une clé API avec la portée `full`. > **Commerce est en alpha:** Commerce est réservé à l’équipe Emailit pendant que nous le testons. Les autres requêtes renvoient `403` avec `error: "commerce_alpha"`. Les clés API ne fonctionnent que dans les espaces de travail qui appartiennent à l’équipe Emailit. Consultez [Qui peut utiliser Commerce](/fr/docs/commerce/#who-can-use-commerce). `POST /coupons/{id}/codes` ## Paramètres de chemin - `id` (string, obligatoire): L’ID du coupon (`cpn_...`) ou la `key` du coupon. ## Corps de la requête Envoyez `codes` ou `generate`. Si vous envoyez les deux, `generate` est utilisé. - `codes` (string[] | string): 10 000 codes au maximum : un tableau, ou un texte avec un code par ligne. Pour un texte CSV, la première colonne est lue et un en-tête comme `code` ou `coupon_code` est ignoré. Un code compte de 2 à 64 lettres, chiffres, `-`, `_` ou `.`, et commence par une lettre ou un chiffre. Les codes qui ne correspondent pas sont renvoyés dans `invalid`. - `generate` (object): Crée des codes aléatoires composés de lettres majuscules et de chiffres, sans `0`, `O`, `1` ni `I`, faciles à confondre. - `count` (entier, obligatoire) : de 1 à 10 000 codes. - `prefix` (chaîne) : 20 lettres, chiffres, `-` ou `_` au maximum, placés devant chaque code. Par exemple `WELCOME-`. - `length` (entier) : nombre de caractères aléatoires après le préfixe, de 4 à 32. Par défaut : 8. Les valeurs hors de cette plage sont ramenées à la borne la plus proche. ## Réponse - `added` (integer): Codes ajoutés à la réserve. - `skipped` (integer): Codes qui étaient déjà dans la réserve. - `invalid` (string[]): Valeurs importées qui ne sont pas des codes valides et n’ont pas été ajoutées. - `coupon` (object): L’[objet coupon](/fr/docs/api-reference/coupons/get/) avec les nouveaux décomptes. Renvoie `404` si aucun coupon ne correspond à `id`, et `422` pour un coupon à code fixe, quand aucun code valide n’a été envoyé, quand plus de 10 000 codes ont été envoyés, ou quand `generate.count` ou `generate.prefix` est hors limites. **Requête** `POST /coupons/{id}/codes` **cURL** ```bash curl -X POST https://api.emailit.com/v2/coupons/welcome-10/codes \ -H "Authorization: Bearer your_api_key" \ -H "Content-Type: application/json" \ -d '{ "generate": { "count": 5000, "prefix": "WELCOME-", "length": 8 } }' ``` **200** ```json { "added": 5000, "skipped": 0, "invalid": [], "coupon": { "object": "coupon", "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ", "key": "welcome-10", "name": "Welcome 10% off", "description": "First-order discount for new subscribers.", "kind": "unique", "static_code": "WELCOME10", "discount_label": "10% off", "expires_at": "2026-12-31T23:59:59.000Z", "codes_total": 5003, "codes_available": 5003, "codes_assigned": 0, "codes_redeemed": 0, "created_at": "2026-10-01T09:00:12.304Z", "updated_at": "2026-10-01T09:00:12.304Z" } } ``` **422** ```json { "message": "Validation failed. codes: Static coupons have one code; set static_code instead.", "errors": { "codes": [ "Static coupons have one code; set static_code instead." ] } } ``` --- Source: https://emailit.com/fr/docs/api-reference/coupons/add-codes/