Route a captured order

Routes a captured order to a fulfilling store, moving it to accepted. The candidate stores are resolved SERVER-SIDE from live stock (the inventory read model) and the store directory — only ACTIVE stores, availability net of reservations — so the request body carries no stock: send {} for ordinary auto-routing. Among the candidates holding enough stock to cover every line, the deepest-stocked store wins (ties by smallest storeId). When none can fully fulfil it, the order moves to rejected — an operational state, not a dead end: POST /orders/{id}/revert steps it back to captured once stock lands. Pass the optional forcedStoreId to MANUALLY override routing and pin the order to a specific store: it is accepted only when that store is a candidate that can fully fulfil the order, else the request fails 422 and the order stays captured (never rejected). 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 when the order is not captured or the forced store cannot fulfil it.

POST /v1/orders/{id}/route

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": "accepted",
  "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

forcedStoreId · string

Optional MANUAL fulfilment-store override (forced routing). Omit to auto-pick the optimal candidate (default, unchanged). When set, routing is PINNED to this storeId: it is accepted only if that store is one of the candidates and holds enough stock to fully fulfil every line; otherwise the request fails 422 (BusinessRuleViolation) and the order stays captured (it is NOT rejected), so another store can be chosen.

Minimum string length: 1

Response

200

application/json

The routed order — accepted onto a store, or rejected when none can fulfil it.

The routed order — accepted onto a store, or rejected when none can fulfil it.

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