Advance an order

Advances an order along its lifecycle: fulfil an accepted order to fulfilled, or cancel a captured / accepted order. The order id comes from the PATH — a body orderId is ignored. Failure conditions: 400 on a malformed body; 404 for an unknown order; 422 on an illegal transition (e.g. fulfilling a still-captured, unrouted order).

POST /v1/orders/{id}/advance

Error

A valid request URL is required to generate request examples

200

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

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.

Path Parameters

id · string · required

Id of the order (commande) to read or transition.

Minimum string length: 1

Body

application/json

action · enum<string> · required

Lifecycle transition to apply: fulfil | cancel.

Available options: fulfil, cancel

Response

200

application/json

The advanced order at its new lifecycle status.

The advanced order at its new lifecycle status.

id · string · required

channel · enum<string> · required

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

deliveryMode · enum<string> · required

Available options: click-and-collect, ship-from-store, endless-aisle

customer · object · required

Show child attributes

lines · object[] · required

Show child attributes

status · enum<string> · required

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

fulfillingStoreId · string | null · required

routingExplanation · object | null · required

Show child attributes

actorId · string · required

capturedAt · string · required