List in-store holds

Returns ONE PAGE of the in-store ‘Reserve here’ holds, optionally narrowed by ?store=<id> and/or ?status=held|fulfilled|cancelled|expired. Use it to render the counter list — page with page/pageSize (max 100) until page reaches pageCount, because a hold left on an unread page is a customer’s unit nobody knows is set aside. total counts the matching holds across ALL pages. No match is an empty items array.

GET /v1/reservations

Error

A valid request URL is required to generate request examples

200

{
  "items": [
    {
      "id": "rsv-ok",
      "skuId": "1bee1106d484160b89bed6acf6bfd209fcb20e32a52e975e946a08c1f8db957e",
      "customerId": "cust-1",
      "storeId": "store-1",
      "quantity": 2,
      "holdUntil": "2999-01-01T00:00:00.000Z",
      "depositReference": "ACPT-1",
      "status": "held",
      "actorId": "cashier-1",
      "heldAt": "2026-01-02T10:00:00.000Z"
    }
  ],
  "total": 1,
  "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

store · string

Narrow to one store's holds (réservations) by store id.

status · enum<string>

Filter by status: held | fulfilled | cancelled | expired.

Available options: held, fulfilled, cancelled, expired

Response

200

application/json

A page of matching reservations (one row per hold) with the pagination totals.

A page of matching reservations (one row per hold) 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