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. Nécessite Idempotency-Key.

La commande est créée en pending. 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.

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 + payment_fee (clamp à 0). Le subtotal lui-même = sum(items[].quantity × (price + Σ variants.price_adjustment)).

shipping_cost, discount et payment_fee sont repris exactement tels qu'envoyés — la seule vérification est que chacun soit ≥ 0. Ils ne sont pas validés contre les tarifs de livraison ni 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 clé, même boutique) sous 24 h, on renvoie la même réponse — la commande est créée exactement une fois. 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 :

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 : n'importe quelle clé plateforme active de la boutique (orders:read est accordé par défaut et n'est pas vérifié séparément en v1 ; seul orders:write est contrôlé, sur les endpoints d'écriture).

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 : n'importe quelle clé plateforme active de la boutique (orders:read n'est pas vérifié séparément en v1).

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. Nécessite Idempotency-Key.

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. Nécessite Idempotency-Key.

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) 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.). Les combinaisons ne sont pas exposées sur l'endpoint produits public (elles le seront en v1.1 comme tableau combinations[] sur GET /v1/products/{id}/combinations). Pour l'instant, le stock par combinaison est appliqué à la confirmation de la commande et reste visible dans le tableau de bord.

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.