List orders (commandes)

Returns one page of the omnichannel order (commande) read model, optionally filtered by status, channel and a free-text search, and sorted (capturedAt / total / id). To find one ticket rather than browse, pass ?search= — it matches the order reference and the customer SERVER-side across the WHOLE book before paginating, so an old ticket is still found (the till’s returns counter drives exactly this). Use page/pageSize (max 100) to walk the result; total/pageCount tell you when to stop. Reach for it to browse the OMS backlog.

GET /v1/orders

Error

A valid request URL is required to generate request examples

200

{
  "items": [
    {
      "id": "WEB-24810",
      "channel": "web",
      "deliveryMode": "click-and-collect",
      "customer": {
        "customerId": "cust-24810",
        "displayName": "Camille Laurent"
      },
      "lines": [
        {
          "skuId": "f139995b359e2702f33b391acb3d42a419197a7b2c09d04c1fe6d97ecefe4feb",
          "quantity": 1,
          "unitPriceCents": 11900
        }
      ],
      "status": "accepted",
      "fulfillingStoreId": "store-lyon",
      "routingExplanation": {
        "basis": "criterion",
        "criterionIndex": 0,
        "criterionKind": "stock-depth",
        "runnerUpStoreId": "store-rivoli"
      },
      "actorId": "seller-1",
      "capturedAt": "2026-07-28T10:00:00.000Z"
    }
  ],
  "total": 15,
  "page": 1,
  "pageSize": 20,
  "pageCount": 1
}

Authorizations

Authorization · string · header · required

Authorization: Bearer <token>. Accepts EITHER a Keycloak access token (scopes-in-token) OR an opaque POS session token; both resolve to the same pos.* scope vocabulary the route guards enforce.

Query Parameters

page · integer · default: 1

1-based page index to return. Defaults to 1.

Required range: 1 <= x <= 9007199254740991

pageSize · integer · default: 20

Rows per page, 1..100. Defaults to 20.

Required range: 1 <= x <= 100

status · enum<string>

Filter by order (commande) lifecycle status.

Available options: captured, accepted, fulfilled, cancelled, rejected

channel · enum<string>

Filter by capture channel (e.g. web | store).

Available options: web, marketplace, mobile-app, in-store

search · string

Free-text search (recherche) matched SERVER-side, case-insensitively, against the order reference (its id) and its customer (display name or id). Applied to the whole order book BEFORE pagination, so a match on an old ticket is still returned. A blank term is a no-op. Combines with status / channel as AND.

sortField · enum<string>

Sort key: capturedAt | total | id (default capturedAt).

Available options: capturedAt, total, id

sortDirection · enum<string>

Sort direction (default desc).

Available options: asc, desc

Response

200

application/json

A page of order views with the pagination totals.

A page of order views with the pagination totals.

items · object[] · required

The rows on this page, in the query's sort order.

Show child attributes

total · integer · required

Total rows matching the filter across ALL pages, not just this one.

Required range: 0 <= x <= 9007199254740991

page · integer · required

The 1-based page number served.

Required range: 0 < x <= 9007199254740991

pageSize · integer · required

Rows requested per page.

Required range: 0 < x <= 9007199254740991

pageCount · integer · required

Total number of pages; stop walking when page reaches it.

Required range: 0 <= x <= 9007199254740991