Bons de réduction

Un bon de réduction est une offre de remise — un pourcentage ou un montant fixe déduit du panier, avec un montant minimum et une période de validité facultatifs — accompagnée des codes que vos clients saisissent lors du paiement pour en profiter. Lorsque vous quittez un autre outil, importez vos bons de réduction en cours et les codes que vous avez déjà envoyés afin qu'ils continuent de fonctionner dans votre boutique, puis relisez chaque bon de réduction pour le vérifier.

Les deux points d'accès nécessitent une clé disposant du droit promotion:read (lecture) ou promotion:write (import).

Points d'accès

Méthode	Chemin	Droit	Limite par lot
POST	`/v1/voucher/import`	`promotion:write`	50 bons de réduction et 500 codes par requête
GET	`/v1/voucher/import`	`promotion:read`	Un bon de réduction

L'objet bon de réduction

Champ	Type	Description
`id`	chaîne	L'identifiant du bon de réduction dans votre boutique, préfixé par `prom_`.
`object`	chaîne	Toujours `promotion`.
`external_id`	chaîne	La référence du bon de réduction dans votre ancien système.
`project`	chaîne	L'identifiant de votre boutique.
`status`	chaîne	`draft`, `scheduled`, `activated`, `paused`, `expired` ou `archived` ; `deleted` une fois supprimé dans votre espace de travail.
`name`	chaîne	Le nom du bon de réduction.
`type`	chaîne	`percentage` ou `fixed_amount`.
`value`	chaîne	La remise : un pourcentage ou un montant, sous forme de chaîne décimale comme `"15.00"`.
`currency`	chaîne	Le code de devise d'un montant fixe, comme `EUR`.
`min_amount`	chaîne	Le montant minimum du panier, sous forme de chaîne décimale. `"0.00"` s'il n'y en a pas.
`audience`	chaîne	`all`, `segment` ou `consumer`.
`starts_at`	entier	Début de validité, en secondes Unix. `0` s'il n'y en a pas.
`ends_at`	entier	Fin de validité, en secondes Unix. `0` s'il n'y en a pas.
`created_at`	entier	Date de création, en secondes Unix.
`updated_at`	entier	Dernière modification, en secondes Unix.
`codes`	tableau	Tous les codes du bon de réduction, triés par code.

Chaque entrée de codes :

Champ	Type	Description
`id`	chaîne	L'identifiant du code dans votre boutique, préfixé par `prco_`.
`object`	chaîne	Toujours `promotion_code`.
`external_id`	chaîne	La référence du code dans votre ancien système ; vide pour un code créé dans votre espace de travail.
`status`	chaîne	`activated`, ou `deleted` une fois supprimé dans votre espace de travail.
`code`	chaîne	Le code que le client saisit.
`customer`	chaîne	L'identifiant dans votre boutique du client auquel le code est réservé (`cust_…`) ; vide pour un code public.
`usage_limit`	entier	Le nombre de fois où le code peut être utilisé. `0` signifie illimité.
`usage_count`	entier	Le nombre de fois où le code a été utilisé.
`starts_at`	entier	Début de validité, en secondes Unix. `0` s'il n'y en a pas.
`expires_at`	entier	Expiration, en secondes Unix. `0` s'il n'y en a pas.
`created_at`	entier	Date de création, en secondes Unix.
`updated_at`	entier	Dernière modification, en secondes Unix.

Importer des bons de réduction

POST /v1/voucher/import crée ou met à jour jusqu'à 50 bons de réduction par requête, chacun avec ses codes. Il suit le contrat d'import commun décrit dans Votre premier appel : items, dry_run, un rapport ligne par ligne.

Champs du bon de réduction

Champ	Type	Obligatoire	Description
`external_id`	chaîne	Oui	Votre référence pour le bon de réduction, jusqu'à 50 caractères, unique dans le lot. Le bon de réduction est reconnu grâce à elle lors de chaque import ultérieur.
`name`	chaîne	Non	Jusqu'à 190 caractères.
`type`	chaîne	Non	`percentage` ou `fixed_amount`.
`value`	nombre ou chaîne	Non	La remise, zéro ou plus, avec jusqu'à 2 décimales. Au plus `100` pour un bon de réduction `percentage`.
`min_amount`	nombre ou chaîne	Non	Le montant minimum du panier, zéro ou plus.
`currency`	chaîne	Non	Un code de devise de 3 à 10 lettres, comme `EUR`.
`starts_at`	entier	Non	Début de validité, en secondes Unix.
`ends_at`	entier	Non	Fin de validité, en secondes Unix.
`audience`	chaîne	Non	`all`, `segment` ou `consumer`.
`status`	chaîne	Non	`draft`, `scheduled`, `activated`, `paused`, `expired` ou `archived`. Un nouveau bon de réduction sans statut est créé en `draft` ; un bon existant conserve son statut.
`created_at`	entier	Non	La date de création d'origine, en secondes Unix. Conservée telle qu'envoyée et jamais modifiée par un import ultérieur.
`codes`	tableau	Non	Les codes du bon de réduction (voir ci-dessous).

Champs du code

Champ	Type	Obligatoire	Description
`external_id`	chaîne	Oui	Votre référence pour le code, jusqu'à 50 caractères, unique dans l'ensemble du lot.
`code`	chaîne	Oui	Le code que le client saisit, de 1 à 190 caractères. Un code est unique dans toute la boutique, sans tenir compte de la casse ni des accents.
`customer_external_id`	chaîne	Non	L'`external_id` d'un client déjà importé, pour lui réserver le code. Omettez-le pour un code public.
`usage_limit`	entier	Non	Le nombre de fois où le code peut être utilisé ; `0` (par défaut) signifie illimité.
`usage_count`	entier	Non	Le nombre de fois où le code a déjà été utilisé. Inchangé si vous l'omettez.
`starts_at`	entier	Non	Début de validité, en secondes Unix.
`expires_at`	entier	Non	Expiration, en secondes Unix.
`status`	chaîne	Non	Seul `activated` est accepté.
`created_at`	entier	Non	La date de création d'origine, en secondes Unix.

Un code invalide entraîne le refus de tout son bon de réduction, et un bon de réduction est enregistré avec tous ses codes ou pas du tout. Les codes que vous omettez lors d'un import ultérieur ne sont jamais supprimés : pour envoyer un bon de réduction de plus de 500 codes, répartissez ses codes sur plusieurs requêtes qui reprennent l'external_id du bon de réduction.

Important — Importez d'abord les clients : un code dont le customer_external_id ne correspond à aucun client de votre boutique est refusé avec Import the customers first. Voir Commandes & logistique.

Le rapport d'import

Chaque entrée acceptée de data ajoute deux champs au rapport commun :

Champ	Type	Description
`codes`	objet	Le nombre de codes du bon de réduction `created`, `updated` et `unchanged`.
`codes_detail`	tableau	Une entrée par code : son `external_id`, son `action` et son `id` (`null` pour une création en mode essai).

Une entrée refusée ne porte que les huit champs communs. Un code déjà utilisé par un autre code de la boutique entraîne le refus de son bon de réduction avec le code 409. Un bon de réduction dont les codes ont changé est signalé comme updated, même si ses propres champs n'ont pas changé.

Exemple

curl

curl https://api.ultineo.com/v1/voucher/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dry_run": false,
    "items": [
      {
        "external_id": "SPRING-2026",
        "name": "Spring sale",
        "type": "percentage",
        "value": 15,
        "min_amount": "50.00",
        "currency": "EUR",
        "audience": "all",
        "status": "activated",
        "starts_at": 1774998000,
        "ends_at": 1777590000,
        "codes": [
          { "external_id": "SPRING-2026-PUBLIC", "code": "SPRING15", "usage_limit": 0, "usage_count": 42 },
          { "external_id": "SPRING-2026-C1001", "code": "SPRING15-MARTIN", "customer_external_id": "C1001", "usage_limit": 1 }
        ]
      }
    ]
  }'

application/json

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "promotion",
    "dry_run": false,
    "data": [
      {
        "index": 0,
        "external_id": "SPRING-2026",
        "action": "created",
        "id": "prom_8d2c5e41a0b7f39e6c14",
        "code": null,
        "title": null,
        "reason": null,
        "notice": [],
        "codes": { "created": 2, "updated": 0, "unchanged": 0 },
        "codes_detail": [
          { "external_id": "SPRING-2026-PUBLIC", "action": "created", "id": "prco_1f6a93c0d4e8b2a75e31" },
          { "external_id": "SPRING-2026-C1001", "action": "created", "id": "prco_7b04e2d9a6c1f835b0d2" }
        ]
      }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Lire un bon de réduction

GET /v1/voucher/import renvoie un bon de réduction avec tous ses codes, y compris le nombre de fois où chaque code a été utilisé.

Paramètre	Emplacement	Description
`external_id`	query	La référence du bon de réduction dans votre ancien système. Prioritaire sur `id`.
`id`	query	L'identifiant du bon de réduction dans votre boutique, préfixé par `prom_`.

Indiquez l'un des deux ; sans l'un ni l'autre, l'appel répond 400 Missing required parameter: external_id. Un bon de réduction absent de votre boutique répond 404 Promotion not found.