Orders overview - Chataigne Docs

The Orders API lets a connected POS or middleware platform retrieve orders created by Chataigne. Chataigne remains the system of record: V1 does not expose POST /orders and does not import externally created orders.

Endpoints

Need	Operation
List orders for one location	`GET /v1/locations/{location_id}/orders`
Retrieve one location order	`GET /v1/locations/{location_id}/orders/{order_id}`
List orders across an organization	`GET /v1/organizations/{organization_id}/orders`
Retrieve one organization order	`GET /v1/organizations/{organization_id}/orders/{order_id}`
Update a POS order status	`PUT /v1/locations/{location_id}/orders/{order_id}/status`

Reading requires orders.read. Updating a status requires orders.write. Every request remains constrained to the locations and organizations authorized for the API key.

Pagination and reconciliation

Order lists use deterministic cursor pagination ordered by immutable (created_at DESC, id DESC) keys. Set limit from 1 to 100 and use either starting_after or ending_before, never both. Filters include status, service_type, location_id on organization lists, and the created_after, created_before, updated_after, and updated_before timestamp bounds. For reconciliation after an unavailable consumer or a webhook incident, capture a high-water timestamp before the first request. Send the previous checkpoint as updated_after and that same high-water value as updated_before on every page, then continue until has_more is false. After the bounded scan completes, advance the checkpoint to the high-water mark. Because timestamp bounds are exclusive, retain a one-millisecond overlap when building the next updated_after value and deduplicate by id plus status_version. This bounded protocol prevents updates made during the scan from moving across its cursor; they are returned by the next scan. Do not assume webhook delivery order is the same as order update order.

Order identity

id is the stable Chataigne order identifier used by API paths and webhook deduplication logic.
short_id is the human-readable number shown to restaurant staff.
location_id identifies the restaurant that owns the order.
status_version increases by one on each canonical status transition.

Items and external references

Products and bundles are returned in the same items array. Inspect type before reading the item-specific fields:

{
  "items": [
    {
      "type": "product",
      "id": "burger-classic",
      "name": "Classic burger",
      "quantity": 2,
      "unit_price": { "amount": 12.5, "currency": "EUR" },
      "modifier_groups": []
    },
    {
      "type": "bundle",
      "id": "lunch-menu",
      "name": "Lunch menu",
      "quantity": 1,
      "unit_price": { "amount": 18, "currency": "EUR" },
      "lines": []
    }
  ]
}

For a product, id is its external SKU reference. A bundle, bundle line, modifier group, and modifier use their persisted external references. Chataigne never substitutes an internal database identifier when an external reference is missing.

A location cannot be activated with an API POS receiver until its active catalog has external references for every sellable product, modifier, modifier group, bundle, and bundle line. If a historical order is nevertheless missing a reference, its primary-receiver delivery is withheld. Observer endpoints still receive the public snapshot with null in place of that reference; Chataigne never exposes an internal identifier.

Amounts and charges

All monetary values use { "amount": number, "currency": string }. The public charges array contains only delivery and service charges, both with exactly the same shape:

{
  "charges": [
    { "type": "delivery", "amount": { "amount": 3.5, "currency": "EUR" } },
    { "type": "service", "amount": { "amount": 1, "currency": "EUR" } }
  ]
}

Provider metadata, internal charge identifiers, internal SKU identifiers, payment credentials, and private POS fields are never exposed. total remains the canonical amount charged for the order and can therefore include provider-specific or private charges that are intentionally omitted from the public charges array.

Fulfillment times

expected_pickup_time is when the order should leave the restaurant or be collected.
expected_delivery_time is the promised customer arrival time for delivery orders.
expected_time is the customer-facing promise: delivery time for delivery, pickup time for collection.

A delivery can therefore have both a courier pickup time and a later customer delivery time. For collection, expected_delivery_time is null.

​Endpoints

​Pagination and reconciliation

​Order identity

​Items and external references

​Amounts and charges

​Fulfillment times

Endpoints

Pagination and reconciliation

Order identity

Items and external references

Amounts and charges

Fulfillment times