Aller au contenu
Docs

Coupons

Créez des coupons et gérez leurs réserves de codes uniques pour vos e-mails.

URL de basehttps://api.emailit.com/v2AuthentificationErreursLimites de débit

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.

  • 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, 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 indique un code dans coupon_codes, le code est marqué comme utilisé. Consultez Produits, coupons et panier.

POST/coupons

Corps de la requête

keystringObligatoire

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.

namestringObligatoire

Nom du coupon affiché dans le tableau de bord, 191 caractères au maximum.

descriptionstring | null

Note pour votre équipe. Un texte plus long est coupé à 1 000 caractères.

kindstring

unique (par défaut) ou static.

static_codestring | 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_labelstring | null

Courte description de la réduction, comme 10% off. Un texte plus long est coupé à 191 caractères.

expires_atstring | 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.

codesstring[] | 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. Renvoie 422 quand un champ n’est pas valide ou qu’un autre coupon a déjà cette clé.

POST/coupons
Terminal
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"]
  }'
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"
}

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.

GET/coupons/{id}

Paramètres de chemin

idstringObligatoire

L’ID du coupon (cpn_...) ou la key du coupon.

L’objet coupon

objectstring

Toujours coupon.

idstring

ID du coupon (cpn_...).

keystring

Le nom que vous utilisez dans le contenu des e-mails : {{coupon "welcome-10"}}. Consultez Produits, coupons et panier.

namestring

Nom du coupon affiché dans le tableau de bord.

descriptionstring | null

Note pour votre équipe.

kindstring

  • 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_codestring | 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_labelstring | null

Courte description de la réduction, comme 10% off.

expires_atstring | null

Passé cette date, les destinataires d’un coupon à codes uniques reçoivent static_code au lieu d’un code.

codes_totalinteger

Codes dans la réserve.

codes_availableinteger

Codes qui peuvent encore être distribués : non attribués à un contact et non utilisés dans une commande.

codes_assignedinteger

Codes attribués à un contact, y compris ceux déjà utilisés.

codes_redeemedinteger

Codes utilisés dans une commande (coupon_codes).

created_at, updated_atstring

Dates de création et de dernière modification du coupon, au format ISO 8601 UTC.

GET/coupons/{id}
Terminal
curl https://api.emailit.com/v2/coupons/welcome-10 \
  -H "Authorization: Bearer your_api_key"
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"
}

Mettre à jour un coupon

Met à jour un coupon. Seuls les champs envoyés changent. Pour ajouter des codes, utilisez Ajouter des codes à un coupon : codes est ignoré dans cette requête. Nécessite une clé API avec la portée full.

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

idstringObligatoire

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. 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 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.

POST/coupons/{id}
Terminal
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" }'
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"
}

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.

GET/coupons

Paramètres de requête

pageinteger

Numéro de page pour la pagination (minimum : 1, par défaut : 1).

limitinteger

Nombre de coupons à renvoyer (minimum : 1, maximum : 100, par défaut : 25).

searchstring

Correspondance insensible à la casse sur le nom ou la clé du coupon.

matchstring

all (par défaut) exige que tous les filtres correspondent. Avec or, il suffit qu’un filtre corresponde. Consultez Filtrage et tri.

orderstring

Clé de tri de cette liste. Consultez les clés de tri ci-dessous.

directionstring

asc ou desc.

Filtres et tri

Les filtres de liste sont des paramètres de requête key.condition=value sur un seul niveau. Consultez Filtrage et tri pour match, order, direction et la liste des conditions par type.

Clés de filtre

CléTypeConditionsRemarques
keystringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
kindenumexact, not_exactValeurs : unique, static
expires_atdateexact, before, after, empty, not_empty
created_atdateexact, before, after, empty, not_empty

Clés de tri

Passez dans order l’une de ces clés et dans direction la valeur asc ou desc : key, name, kind, expires_at, created_at

Réponse

Renvoie une page d’objets coupon 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.

GET/coupons
Terminal
curl "https://api.emailit.com/v2/coupons?kind.exact=unique" \
  -H "Authorization: Bearer your_api_key"
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
}

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.

DELETE/coupons/{id}

Paramètres de chemin

idstringObligatoire

L’ID du coupon (cpn_...) ou la key du coupon.

DELETE/coupons/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/coupons/cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "object": "coupon",
  "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ",
  "deleted": true
}

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.

GET/coupons/{id}/codes

Paramètres de chemin

idstringObligatoire

L’ID du coupon (cpn_...) ou la key du coupon.

Paramètres de requête

pageinteger

Numéro de page pour la pagination (minimum : 1, par défaut : 1).

limitinteger

Nombre de codes à renvoyer (minimum : 1, maximum : 100, par défaut : 50).

statusstring

  • 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.

formatstring

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.

matchstring

all (par défaut) exige que tous les filtres correspondent. Avec or, il suffit qu’un filtre corresponde. Consultez Filtrage et tri.

orderstring

Clé de tri de cette liste. Consultez les clés de tri ci-dessous.

directionstring

asc ou desc.

Filtres et tri

Les filtres de liste sont des paramètres de requête key.condition=value sur un seul niveau. Consultez Filtrage et tri pour match, order, direction et la liste des conditions par type.

Clés de filtre

CléTypeConditionsRemarques
codestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
emailstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
assigned_atdateexact, before, after, empty, not_empty
redeemed_atdateexact, before, after, empty, not_empty
created_atdateexact, before, after, empty, not_empty

Clés de tri

Passez dans order l’une de ces clés et dans direction la valeur asc ou desc : code, email, assigned_at, redeemed_at, created_at

Réponse

Renvoie une page de codes de coupon dans data, avec total_records, next_page_url et previous_page_url. Chaque code a :

objectstring

Toujours coupon_code.

idstring

ID du code (cpc_...).

codestring

Le code.

contact_id, emailstring | null

Le contact auquel le code est attribué, ou null.

source_idstring | null

La campagne (cmp_...) ou l’automatisation (aut_...) dont l’e-mail a reçu le code.

assigned_atstring | null

Date d’attribution du code.

redeemed_at, redeemed_order_idstring | null

Date à laquelle le code a été utilisé, et commande qui l’a utilisé (ord_...).

created_atstring

Date d’ajout du code à la réserve.

GET/coupons/{id}/codes
Terminal
curl "https://api.emailit.com/v2/coupons/welcome-10/codes?status=assigned&limit=2" \
  -H "Authorization: Bearer your_api_key"
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
}

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 (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.

POST/coupons/{id}/codes

Paramètres de chemin

idstringObligatoire

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é.

codesstring[] | 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.

generateobject

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

addedinteger

Codes ajoutés à la réserve.

skippedinteger

Codes qui étaient déjà dans la réserve.

invalidstring[]

Valeurs importées qui ne sont pas des codes valides et n’ont pas été ajoutées.

couponobject

L’objet coupon 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.

POST/coupons/{id}/codes
Terminal
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 } }'
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"
  }
}

Cette page vous a-t-elle été utile ?

Merci pour votre retour.

Merci, nous lisons chaque message.

Esc

Populaires

↑↓pour naviguer↵pour ouvrirEscpour fermer