Status management - Chataigne Docs

A connected POS updates a Chataigne order with:

PUT /v1/locations/{location_id}/orders/{order_id}/status
Idempotency-Key: pos-transition-0189
Content-Type: application/json

{
  "status": "accepted",
  "reason": "Accepted by the kitchen"
}

Idempotency-Key is required. Reusing a key with the same body returns the original response; reusing it with another body is rejected. Generate a durable key for each intended transition and persist it until the request has completed.

Canonical status lifecycle

The current canonical values are:

received
accepted
in_preparation
awaiting_shipment
awaiting_collection
in_delivery
completed
rejected
cancelled
delivery_failed

received is created by Chataigne and cannot be submitted as a target. Completed, rejected, cancelled, and failed delivery states are terminal. awaiting_collection is not valid for delivery orders; awaiting_shipment is not valid for collection orders. A transition outside the allowed lifecycle is rejected.

Submitting the order’s current status is a successful no-op. It does not increment status_version or emit a duplicate status event.

Bidirectional updates

Status changes can originate from the POS, Chataigne operators, scheduled automation, the ordering flow, or a delivery provider. Every accepted transition passes through the same state machine, becomes the canonical order status, and increments status_version. Use status_version to reject stale webhook updates in your system. Webhook delivery is at least once and can occur out of order after retries. A payload with a version lower than or equal to the highest version already processed for that order can be acknowledged and ignored. When a POS integration or API receiver submits a status, Chataigne applies the first valid transition that reaches the database. A concurrent writer that observed the previous version receives 409 order_status_conflict; it must retrieve the current order before deciding whether to retry. Accepted order.status.updated events are delivered to the primary receiver and subscribed observers, including when the source is a synchronous POS.

Conflict handling

Response	Meaning	Action
`200`	Applied, replayed, or already at that status	Store the returned order and version
`400`	Malformed body or invalid lifecycle transition	Correct the target status
`404`	Order is outside the authorized location or does not exist	Reconcile the order identifier and scope
`409`	Idempotency conflict or concurrent status change	Retrieve the order and decide from its current status/version

A 2xx webhook response only acknowledges receipt. If your POS cannot accept an order, acknowledge the webhook, then submit rejected through the status endpoint with a durable idempotency key and an optional reason.

​Canonical status lifecycle

​Bidirectional updates

​Conflict handling

Canonical status lifecycle

Bidirectional updates

Conflict handling