Commande (order)
Une order est une commande commerciale passée par un acheteur. Elle porte les montants, les lignes d'article et le statut de fulfillment, et sert de pivot entre la session de paiement, la facturation et le suivi opérationnel de la livraison.
Rôle
La commande modélise le cycle de vie commercial d'un achat : de la création initiale jusqu'à la livraison et la clôture. Elle peut être créée directement via l'API ou produite automatiquement par un processus d'orchestration à l'issue d'une checkout session.
La commande est également le point d'ancrage naturel pour la facturation : les factures et avoirs peuvent être créés directement depuis une commande, ou être liés à une commande existante après coup.
Identifiant et structure
Chaque commande porte un identifiant stable préfixé par ord_.
{
"object": "order",
"id": "ord_7e3b9f2a1c4d8e5f",
"buyer_id": "cmp_3a8f1d9c2b4e7f6a",
"buyer_contact_id": "ctc_d12e3f4a5b6c7d8e",
"checkout_session_id": "cs_5e2d8f1a9b3c4d7e",
"source_reference": "ORDER-2026-00842",
"status": "confirmed",
"currency": "eur",
"amount_excluding_tax": 100000,
"amount_tax": 20000,
"amount_including_tax": 120000,
"metadata": {},
"confirmed_at": "2026-06-17T10:05:00.000Z",
"fulfilled_at": null,
"closed_at": null,
"created_at": "2026-06-17T10:00:00.000Z",
"updated_at": "2026-06-17T10:05:00.000Z"
}Champs
| Champ | Type | Description |
|---|---|---|
id | string | Identifiant de la commande (préfixe ord_). |
object | string | Toujours "order". |
buyer_id | string | Entreprise acheteuse (cmp_…). Requis pour émettre une facture depuis la commande. |
buyer_contact_id | string | Contact acheteur (ctc_…). Optionnel. |
checkout_session_id | string | Session de paiement ayant produit cette commande (cs_…). Optionnel. |
sales_channel | enum | null | Canal de vente : web, pos, admin, marketplace, call_center, edi, other ou null. |
billing_details | object | null | Coordonnées de facturation structurées de la commande. |
shipping_details | object | null | Coordonnées de livraison structurées de la commande. |
status | enum | Statut de la commande : draft, created, confirmed, fulfilled, completed, cancelled. |
currency | string | Code devise ISO 4217 en minuscules (ex. eur). |
amount_excluding_tax | integer | Montant HT en centimes. Doit satisfaire : HT + taxe = TTC. |
amount_tax | integer | Montant de la taxe en centimes. |
amount_including_tax | integer | Montant TTC en centimes. |
source_reference | string | Référence dans votre système (numéro de commande interne, panier…). |
metadata | object | Map plate de scalaires `string | number | boolean`, selon la convention metadata de l’API. |
confirmed_at | datetime | Horodatage de confirmation. Renseigné au plus tôt à confirmed. |
fulfilled_at | datetime | Horodatage de livraison. Renseigné à partir de fulfilled. |
closed_at | datetime | Horodatage de clôture (completed ou cancelled). |
created_at | datetime | Date de création. |
updated_at | datetime | Date de dernière mise à jour. |
Cycle de vie
La commande suit un cycle de vie linéaire avec deux états finaux. Le statut initial (draft ou created) est choisi à la création — les statuts suivants ne sont accessibles que via les endpoints de transition dédiés.
Statuts
| Statut | Description | Final |
|---|---|---|
draft | Brouillon non encore actif. Modifiable. Ne peut pas être confirmé — seule sortie possible : annulation. | non |
created | Commande active, transmise à l'acheteur. Modifiable. Peut être confirmée ou annulée. | non |
confirmed | Commande acceptée. Non modifiable. Peut être livrée ou annulée. | non |
fulfilled | Marchandises ou services livrés. Non modifiable. | non |
completed | Commande terminée et clôturée. | oui |
cancelled | Commande annulée. Accessible depuis draft, created ou confirmed. | oui |
Transitions
| Action | Endpoint | Depuis | Vers | Timestamps mis à jour |
|---|---|---|---|---|
| Confirmer | POST /:id/confirm | created | confirmed | confirmed_at |
| Livrer | POST /:id/fulfill | confirmed | fulfilled | fulfilled_at |
| Compléter | POST /:id/complete | fulfilled | completed | closed_at |
| Annuler | POST /:id/cancel | draft, created, confirmed | cancelled | closed_at |
Les timestamps de progression sont cumulatifs : passer directement à fulfilled sans être passé explicitement par confirmed renseigne également confirmed_at. De même, complete renseigne fulfilled_at s'il était encore null.
draft ou created peuvent être modifiées via POST /:id (montants, lignes, acheteur, métadonnées). À partir de confirmed, tous les champs sont figés — toute correction passe par une annulation et une nouvelle commande, ou par un avoir.Lignes d'article
Les lignes d'article décrivent le détail des produits ou services compris dans la commande. Elles peuvent être fournies à la création et remplacées atomiquement lors d'une mise à jour (tant que la commande est en draft ou created). Elles sont ensuite accessibles via GET /v1/orders/:id/line-items.
{
"object": "line_item",
"id": "li_a1b2c3d4e5f6",
"product_name": "Abonnement Pro",
"description": "Accès 12 mois",
"line_type": "service",
"product_reference": "PROD-PRO-12M",
"quantity": 1,
"unit_amount_excluding_tax": 100000,
"unit_amount_including_tax": 120000,
"amount_excluding_tax": 100000,
"amount_tax": 20000,
"amount_including_tax": 120000,
"currency": "eur",
"tax": { "type": "percent", "rate": 0.20, "code": "TVA20" }
}| Champ | Type | Description |
|---|---|---|
product_name | string | Nom du produit ou service. Requis. |
description | string | Description complémentaire. Optionnel. |
line_type | enum | product, service, shipping, discount, fee. Optionnel. |
product_reference | string | Référence produit dans votre catalogue. Optionnel. |
quantity | integer | Quantité (entier positif). |
unit_amount_excluding_tax | integer | Prix unitaire HT en centimes. |
unit_amount_including_tax | integer | Prix unitaire TTC en centimes. |
amount_excluding_tax | integer | Montant ligne HT (= unit_ht × quantity si absent). |
amount_tax | integer | Montant taxe de la ligne. |
amount_including_tax | integer | Montant ligne TTC. |
currency | string | Devise de la ligne. Doit correspondre à la devise de la commande. |
tax | object | Détail de la taxe : type (percent, fixed, none), rate, code, amount. |
La contrainte d'égalité HT + taxe = TTC s'applique à chaque ligne individuellement. Les montants de ligne (amount_*) sont calculés automatiquement si absents (unit_amount × quantity).
Facturation
Une commande peut être associée à une ou plusieurs factures ou avoirs. Deux modes sont disponibles : créer une facture directement depuis la commande, ou lier des factures existantes.
Créer une facture depuis la commande
POST /v1/orders/:id/invoices crée une facture héritant automatiquement du merchant_id, du buyer_id et de la currency de la commande — ces champs ne peuvent pas être surchargés. La commande doit avoir un buyer_id pour qu'une facture puisse être émise.
POST /v1/orders/ord_7e3b/invoices
{
"type": "invoice",
"amount_excluding_tax": 100000,
"amount_tax": 20000,
"amount_including_tax": 120000,
"reference": "FAC-2026-00042",
"issue_date": "2026-06-17",
"due_date": "2026-07-17",
"issue": true
}Passer "issue": true émet immédiatement la facture (transition vers status: "issued") et déclenche l'événement invoice.issued en plus de invoice.created. Pour les avoirs, utilisez "type": "credit_note" et référencez la facture d'origine via source_invoice_id.
Lier des factures existantes
Des factures existantes (créées indépendamment) peuvent être rattachées à la commande.
| Endpoint | Effet |
|---|---|
GET /v1/orders/:id/invoices | Liste toutes les factures liées à la commande. |
POST /v1/orders/:id/invoice-links | Remplace atomiquement l'ensemble des liens. Envoie { "invoice_ids": ["inv_…", …] }. |
DELETE /v1/orders/:id/invoice-links/:invoice_id | Retire un lien sans toucher aux autres. |
Les factures liées doivent appartenir au même marchand et au même acheteur que la commande. Le lien est purement relationnel — il n'affecte pas le statut de la facture.
Dans les processus
Il n'existe pas de node dédié à la création ou aux transitions d'une commande. L'objet est géré via des appels API directs depuis vos systèmes ou via des actions HTTP dans un processus d'orchestration.
La commande peut être passée en paramètre à certains nodes de paiement — par exemple create_psp_payment accepte un champ order optionnel pour rattacher le paiement à la commande correspondante. Une fois persistée, elle est récupérable dans un processus via le helper générique fetch_order.
Événements
| Événement | Déclencheur |
|---|---|
order.created | La commande vient d'être créée. |
order.updated | La commande a été mise à jour (montants, acheteur, lignes…). |
order.confirmed | La commande est passée à "confirmed". |
order.fulfilled | La commande est passée à "fulfilled". |
order.completed | La commande est passée à "completed". |
order.cancelled | La commande est passée à "cancelled". |
Les événements de transition (confirmed, fulfilled, completed, cancelled) incluent un diff avec le statut final dans after. L'événement order.updated inclut un diff avec le statut précédent dans before et les champs modifiés dans after.