Les commandes sont le cœur de la plateforme. Chaque commande :

Voici la carte exacte des transitions appliquée par l'API, état par état :

L'annulation n'est légale que depuis pending, confirmed et processing — une commande shipped ou delivered ne peut plus être annulée.

Un PATCH vers le statut que la commande porte déjà est un 200 sans effet.

cancelled et returned sont terminaux — pas de transition de sortie.

Créer une commande pour la boutique appelante. Utilisé par les thèmes personnalisés, les apps mobiles / natives, les revendeurs, et toute vitrine headless qui soumet ses commandes depuis son propre serveur au lieu d'utiliser le checkout intégré de la vitrine.

Auth : clé plateforme avec orders:write et orders:read. Nécessite Idempotency-Key. La réponse relit la commande : une clé qui n'a que orders:write enregistre la commande mais reçoit 403 forbidden, et un nouvel essai avec la même Idempotency-Key renvoie ce même 403.

La commande est créée en pending. Par défaut, le stock n'est PAS engagé à la création : c'est la première entrée dans un état engagé (confirmed, processing, shipped ou delivered) qui décrémente le stock, comme dans le flux du tableau de bord. Intentionnel : ça laisse à votre équipe le temps de filtrer les fakes / doublons / non-réponses avant de toucher à l'inventaire. Une boutique dont Commandes → Paramètres d'affichage → Déduction du stock est réglé sur Dès la réception de la commande voit son stock pris dès que l'API crée la commande.

Les clients sont dédupliqués par boutique + téléphone. Si un client avec ce téléphone existe déjà dans votre boutique, sa fiche est mise à jour (nom, wilaya, commune, adresse, email) et réutilisée. Sinon, une nouvelle fiche est créée.

Important — tarification autoritative côté serveur. Vous ne précisez pas le prix de la ligne. C'est toujours le prix catalogue courant du produit qui est appliqué. Si vous envoyez un champ price, il est ignoré.

Le price_adjustment de chaque variante est lui aussi autoritatif côté serveur : pour chaque paire (group_name, option_name) qui correspond à une vraie option du produit, DZBuild substitue le price_adjustment du catalogue. Votre valeur ne survit que pour les paires absentes du catalogue — une tolérance volontaire pour les intégrations obsolètes — donc une « remise » négative que vous inventez est silencieusement écartée pour toute option réelle. Traitez price_adjustment en entrée comme purement informatif : renvoyez la valeur lue sur GET /v1/products/{id} pour que votre total côté client corresponde à celui du serveur.

Chaque objet variante décrit un choix d'option pour un groupe de variantes du produit :

Envoyez un objet variante par groupe choisi sur la ligne. Donc "T-shirt rouge taille L" devient 2 entrées (une pour Color/Red, une pour Size/L). DZBuild les rend sur la page commande du dashboard exactement comme si le client avait cliqué sur la vitrine.

Pour les produits utilisant des variantes par pièce (ex. offre "achetez 3 t-shirts, choisissez une couleur par pièce"), utilisez quantity = 1 par ligne et créez une ligne par pièce — c'est le mapping le plus propre.

Le total est calculé côté serveur : subtotal + shipping_cost - discount (jamais sous 0), où shipping_cost est le montant calculé par le serveur lui-même. Le subtotal lui-même = sum(items[].quantity × (price + Σ variants.price_adjustment)).

Seul discount est repris de votre corps de requête. Il doit être ≥ 0, il est plafonné au sous-total plus la livraison, et il n'est pas vérifié contre les codes promo de votre boutique : POST /v1/orders ne doit donc être appelé que depuis un serveur de confiance, jamais depuis du code navigateur ou applicatif qu'un client peut altérer.

La création d'une commande renvoie HTTP 200, pas 201 — ne testez pas le code de statut ; vérifiez data.id / data.order_number. Le corps a la même forme que GET /v1/orders/{id} — entièrement peuplé avec totaux calculés, bloc client normalisé, et lignes que vous venez de créer (avec leurs variantes).

order_number a le format ORD-{store_id}-{YYYYMMDD}-{8 caractères hex majuscules}. Les commandes issues d'une landing page utilisent LP-{8 caractères hex majuscules}. Les commandes créées avant le 2026-06-02 portent un suffixe hérité de 4 caractères hex : un parseur doit accepter les deux longueurs.

Plafond mensuel de commandes. Le plan Free est plafonné à 30 commandes par mois calendaire ; Pro, Unlimited et Enterprise sont sans plafond. Un nom de plan non reconnu retombe également sur le plafond Free de 30/mois. Le compteur est mensuel calendaire et couvre toutes les sources de commandes (vitrine + landing page + tableau de bord + API).

Chaque POST doit porter un en-tête Idempotency-Key. Si vous rejouez la même requête (même Idempotency-Key, même clé API, mêmes octets de corps) sous 24 h, on renvoie la même réponse avec Idempotency-Replay: 1 : la commande est créée exactement une fois. Les réponses d'erreur sont rejouées aussi, sauf 429 et 5xx, et la même Idempotency-Key avec un corps différent répond 422 idempotency_key_reuse : envoyez une commande corrigée avec une nouvelle clé. Voir Idempotence.

Créer une commande déclenche order.created vers tous les abonnements /v1/webhooks à cet événement. Voir Événements webhook.

⚠️ Attention — /v1/webhooks ne voit que l'activité API

Les abonnements /v1/webhooks se déclenchent uniquement pour les changements effectués via l'API v1. Les commandes passées sur la vitrine ou une landing page, et les changements de statut faits dans le tableau de bord, ne déclenchent pas order.created / order.confirmed / order.shipped.

Pour des événements couvrant toute l'activité commandes, utilisez l'add-on Webhooks (/dashboard/addons → « Webhooks — Connect n8n, Make & Zapier », nécessite le plan Unlimited), qui capte toutes les commandes quelle que soit leur origine — ou continuez à interroger GET /v1/orders?since=….

Une commande créée via l'API est un insert allégé. Comparée à une commande vitrine, landing page ou tableau de bord, elle ne :

Le marchand reçoit bien la notification habituelle de nouvelle commande, la même que pour une commande vitrine.

Notez aussi qu'un client créé par l'API stocke la chaîne customer.name entière dans first_name et laisse last_name vide ; pour un client existant retrouvé par téléphone, seul first_name est écrasé et tout last_name existant reste intact.

Liste les commandes. Pagination par curseur.

Auth : clé avec orders:read (incluse dans les scopes par défaut). Une clé sans ce scope reçoit 403 forbidden « Missing scope: orders:read ».

Un status invalide ou un since non analysable est silencieusement ignoré — vous recevez la liste non filtrée, pas un 400. Il n'y a pas de filtre payment_status en v1 ; filtrez côté client.

La vue liste est volontairement compacte (pas d'items, pas de variantes). Appelez GET /v1/orders/{id} pour le détail complet.

Détail complet avec lignes, variantes et bloc client.

Auth : clé avec orders:read. Une clé sans ce scope reçoit 403 forbidden.

store_seq est le numéro affiché dans le tableau de bord (#644) ; une création via l'API numérote la commande avant de répondre, et dans le rare cas où la numérotation échoue il vaut null jusqu'à ce qu'il soit rempli peu après. shipment.sent_to_delivery passe à true quand le transporteur a accepté le colis ; delivery_company est le transporteur (son slug) et delivery_tracking son numéro de suivi. shipment.last_send_failure est le dernier envoi refusé pour cette commande (at, provider, message du transporteur), ou null si aucun envoi n'a échoué. Il vaut toujours null dès que sent_to_delivery est true : un échec antérieur n'apparaît plus après un envoi réussi. La création, la mise à jour et l'annulation renvoient le même objet.

Le tableau variants de chaque article est la source de vérité de ce que le client a choisi. Chaque entrée a order_item_id, group_name, option_name, color_code (variantes couleur), et price_adjustment (le supplément par pièce, renvoyé comme string JSON et non comme nombre). Pour les offres multi-pièces, vous verrez plusieurs entrées de variantes sur le même article avec des regroupements effectifs différents — voir notes par pièce ci-dessous.

Les add-ons produit (les extras payants à champs personnalisés qu'un marchand configure sur un produit) n'ont aucune surface en v1 : vous ne pouvez pas les envoyer sur POST /v1/orders, et GET /v1/orders/{id} ne renvoie aucune entrée d'add-on. Une commande passée sur la vitrine avec des add-ons se relit via l'API avec le montant des add-ons déjà intégré dans items[].price (et donc dans amounts.subtotal) — mais sans ligne d'add-on, sans titre et sans attribution de fichier.

Auth : clé plateforme avec orders:write et orders:read. Nécessite Idempotency-Key. Sans orders:read, le statut change quand même, mais la réponse est 403 forbidden.

Le corps doit être {"status": "<un des 7>"}. On valide la transition contre le tableau du Cycle de vie ; sinon on renvoie 400 avec les états suivants légaux. Un PATCH vers le statut courant de la commande est un 200 sans effet.

Renvoie 200 et le détail commande à jour. Les transitions concurrentes sur une même commande sont sérialisées : si une autre requête a changé le statut avant vous, la vôtre échoue proprement en bad_request (« order status changed concurrently; retry ») au lieu de s'appliquer deux fois.

Les états à stock engagé sont confirmed, processing, shipped et delivered.

Le stock n'est pas validé : la décrémentation est bornée à zéro, donc une survente n'est jamais rejetée, et un problème de stock ne fait jamais échouer ni annuler le changement de statut. Le stock se comporte exactement comme pour les commandes gérées depuis le tableau de bord.

Endpoint de commodité — exactement équivalent à PATCH /v1/orders/{id} avec {"status":"cancelled"}. Même table de transitions, aucune permission supplémentaire. L'annulation n'est légale que depuis pending, confirmed et processing ; depuis shipped ou delivered vous obtenez 400 bad_request (ces états ne peuvent aller que vers delivered / returned).

Auth : clé plateforme avec orders:write et orders:read. Nécessite Idempotency-Key. Sans orders:read, la commande est quand même annulée, mais la réponse est 403 forbidden.

Remet la commande au transporteur de la boutique, le même envoi que le bouton du tableau de bord. Un colis ne peut pas être rappelé une fois chez le transporteur : chaque envoi demande donc deux appels, et le marchand approuve le premier.

Auth : clé avec delivery:send. Nécessite Idempotency-Key. Les clés créées dans Paramètres → API ne portent pas ce scope et reçoivent 403 forbidden ; une application l'obtient quand le marchand l'approuve à l'installation.

L'envoi tourne normalement en arrière-plan et répond 202 avec queued: true. Lisez GET /v1/orders/{id} jusqu'à ce que shipment.sent_to_delivery soit true avec un delivery_tracking, ou que shipment.last_send_failure montre le refus du transporteur. Si le traitement en arrière-plan n'est pas disponible, l'envoi se fait dans la requête : 200 avec sent, provider et tracking, ou 422 courier_refused avec le message du transporteur. Une fois le colis accepté par le transporteur, une commande pending ou confirmed passe en processing, ce qui prend le stock s'il ne l'était pas encore. Les commandes de type de livraison pickup ne sont jamais remises à un transporteur. Un envoi en arrière-plan arrêté avant l'appel au transporteur, par exemple pour une commande pickup ou un transporteur non lié, répond quand même 202 et ne change aucun des deux champs shipment.

Les variantes font qu'un seul produit couvre plusieurs options (couleur, taille, matière, capacité, …). Sur la vitrine, les clients cliquent sur des cartes de variantes pour choisir ; via l'API, vous envoyez les options choisies dans la commande.

Un produit a 0 ou + groupes de variantes. Un groupe a 0 ou + options. Chaque option peut avoir :

Lisez GET /v1/products/{id} pour voir tous les groupes et options d'un produit :

Un produit avec 2 couleurs × 3 tailles a 6 combinaisons.

Convertissez la sélection client en une entrée variante par groupe choisi. Pour "T-shirt rouge taille L" :

Les noms envoyés sont stockés tels quels sur la commande — ils doivent matcher ce qu'a renvoyé GET /v1/products/{id}. price_adjustment est ajouté au prix de la ligne (donc final_price = product.price + Σ price_adjustment), mais pour toute paire présente dans le catalogue le serveur substitue sa propre valeur : envoyez donc le chiffre du catalogue.

Si le marchand active variant_stock_enabled sur un produit, chaque option de variante porte son propre compteur de stock. Lisez-le depuis options[].stock. L'API ne vous bloque pas pour créer une commande avec quantity > stock ; c'est l'arbitrage du marchand. Le stock est décrémenté à la première entrée dans un état engagé (confirmed, processing, shipped, delivered), ou dès la création sur une boutique qui déduit le stock dès la réception de la commande, et n'est jamais validé : la décrémentation est bornée à zéro, donc une survente est enregistrée plutôt que rejetée.

Si combination_stock_enabled est on, le stock est suivi par combinaison (Red+L = 5, Red+M = 8, etc.). GET /v1/products/{id} les renvoie dans combinations[] (chacune avec id, sku, stock, is_active et ses options), avec combination_count ; la liste s'arrête à 300 entrées et combinations_truncated indique si elle a été coupée. Voir Produits. Le stock par combinaison bouge au même moment que le reste du stock de la commande.

L'add-on Cascading Variants permet au marchand de faire dépendre les options du groupe B de la sélection du groupe A (ex. "Marque → Modèle" — choisir "Apple" pour Marque ne montre que "iPhone 15" / "iPhone 14" pour Modèle). Cet add-on nécessite le plan Pro.

GET /v1/products/{id} n'expose aucune information de cascade — le mappage parent/enfant n'est appliqué que sur la vitrine et dans le tableau de bord. Votre client ne peut pas découvrir les règles de cascade via l'API en v1 : codez-les en dur, ou lisez-les depuis le tableau de bord. Envoyer une combinaison invalide crée quand même la commande (on ne bloque pas) — mais le marchand la rejettera au confirm.

Certains marchands utilisent le type image_text (vignette à côté du libellé). Sur l'API, vous envoyez toujours group_name + option_name — l'image est purement une affaire de vitrine et n'est pas dans la payload de commande.

Si le marchand fait une offre "Achetez 3, mixez les couleurs", le client choisit une variante différente par pièce. Sur l'API :

Trois lignes séparées, chacune quantity = 1. Ainsi la page commande dashboard affiche la couleur de chaque pièce proprement.

Vous construisez une vitrine React/Vue/Next.js qui parle à l'API au lieu d'utiliser les thèmes intégrés DZBuild. Flow :

Voir le guide Thèmes & vitrines personnalisés pour un walkthrough complet.

Utilisez le filtre since :

Le polling est le bon outil ici. Un abonnement /v1/webhooks sur order.created ne couvre que les commandes créées par votre propre intégration via l'API — les commandes vitrine et landing page ne le déclenchent jamais, il ne peut donc pas remplacer le balayage since. Voir Webhooks.