Ventes
Capacités orders.read (les commandes à venir) et orders.history (l'import des commandes passées).
order.upserted
La commande entière, à chaque changement. Renvoyer la même commande ne compte rien deux fois : Kult
Lab la reconnaît par son orderId et met ses lignes à jour par leur lineId.
| Champ | Type | Obligatoire | Sens |
|---|---|---|---|
orderId | identifiant | oui | |
reference | texte | oui | ce que le commerçant lit |
placedAt | instant | oui | |
customerId | identifiant | non | absent : une commande au nom de personne |
stage | étape | oui | voir plus bas |
paid | booléen | oui | à part de stage : une commande peut partir sans être payée |
totalCents | entier | oui | ce que paie le client, livraison comprise, TTC |
totalExclVatCents | entier | oui | |
shippingCents | entier | oui | |
orderDiscountCents | entier | oui, 0 par défaut | une remise sur la commande, non répartie sur les lignes |
lines | objets | oui | voir plus bas |
payments | { name, amountCents }[] | oui | [] tant que rien n'est encaissé |
carrier | { ref, name } | non | absent : rien à expédier |
history | { stage, at }[] | non | du plus ancien au plus récent ; il date la préparation et l'expédition |
C'est une déclaration complète : envoyez payments, customerId et carrier dès qu'ils
existent.
Une ligne
{
"lineId": "4512",
"productId": "NOZA-CEND0210",
"label": "Cookies Gelato, 5 graines",
"quantity": 2,
"unitPriceCents": 2400,
"totalCents": 4800,
"totalExclVatCents": 4000,
"discountCents": 0
}
lineId doit rester le même d'un envoi à l'autre. totalExclVatCents et discountCents sont
facultatifs.
Les étapes
stage | Sens |
|---|---|
awaiting_payment | en attente de paiement |
to_prepare | à préparer, payée ou non |
ready_for_pickup | prête à être retirée |
shipped | expédiée |
delivered | livrée |
cancelled | annulée |
refunded | remboursée |
Il n'y a pas d'étape personnalisée : votre application traduit ses propres états en ces sept-là, une
fois, dans son code. Une commande refunded a été payée, une commande awaiting_payment ne l'est pas :
toute autre combinaison avec paid est refusée (invalid_value).
order.refunded
L'argent rendu, en totalité ou en partie, passe toujours par ce document.
{
"refundId": "R-881",
"orderId": "10412",
"refundedAt": "2026-11-02T10:15:00+01:00",
"reference": "AVOIR-881",
"customerId": "c-2231",
"totalCents": -4800,
"totalExclVatCents": -4000,
"lines": [
{ "lineId": "4512", "productId": "NOZA-CEND0210", "label": "Cookies Gelato, 5 graines", "quantity": -2, "unitPriceCents": 2400, "totalCents": -4800 }
]
}
Les montants et les quantités sont négatifs. Un total positif est refusé.
Une commande passée à refunded ou cancelled sort du suivi des commandes, et ne retire aucun euro
du chiffre d'affaires. Envoyez donc les deux : l'étape sur la commande, l'argent sur son
remboursement. Une vérification cherche les commandes remboursées sans document.
L'import du passé
Quand orders.history est vérifiée, le commerçant peut importer les commandes antérieures à
l'activation. Kult Lab les lit par la commande order.export, qui rend des
order.upserted portant leurs remboursements dans refunds[].