> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chataigne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Orders overview

> Read Chataigne orders from a POS or middleware integration.

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:

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

## 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:

```json theme={null}
{
  "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`.