List automatic promotion rules

Browses the catalogue of AUTOMATIC promotion rules — the reductions the till applies on its own when a cart matches, with no promo code and no manager approval. Use this to answer ‘what offers are running?’, to find a rule’s id before reading or re-configuring it, or to audit what is scheduled or expired. Filter with status (active right now / scheduled for a future window / expired) and type (bogo buy-X-get-Y, threshold quantity-triggered, bundle fixed price for a set). Walk pages with page/pageSize (max 100) until page reaches pageCount. Rows are the DIRECTORY projection — id, name, type, status, validFrom, validUntil and nothing else. The SKU-level reward mechanics (skuId, minQuantity, reward, components, buySkuId, …) are NOT exposed by this endpoint and NOT by any other read in the API: GET /v1/promotions/{id} returns the same six fields. Do not plan on fetching them later. This lists rules only: presented promo codes live at GET /v1/coupons, and manually authorised ticket reductions are not listed here at all.

GET /v1/promotions

Error

A valid request URL is required to generate request examples

200

{
  "items": [
    {
      "id": "promo-threshold-tshirt",
      "name": "-10% T-shirts dès 2",
      "type": "threshold",
      "status": "active",
      "validFrom": "2026-01-01T00:00:00.000Z",
      "validUntil": "2026-12-31T00:00:00.000Z"
    }
  ],
  "total": 8,
  "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

type · enum<string>

Available options: bogo, threshold, bundle

status · enum<string>

Available options: active, scheduled, expired

sortField · enum<string>

Available options: name, validFrom

sortDirection · enum<string>

Available options: asc, desc

Response

200

application/json

A page of promotion directory rows with the pagination totals.

A page of promotion directory rows 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