List the coupon catalogue (code promo)

Returns EVERY authored promo code — active and deactivated alike — each with its terms and its redemptionCount from the ledger. This is the operation to reach for when you need a coupon’s id (codes are what customers type, ids are what POST /v1/coupons/{id}/deactivate takes), when you want to know how much of a campaign has been consumed. It is PAGINATED: page with page/pageSize (max 100) until page reaches pageCount. Do NOT treat it as a uniqueness check before minting a code: nothing enforces uniqueness on code, and listing then creating is a race, not a safeguard (solya-pos#944). It does NOT tell you whether a code applies to a given basket — use POST /v1/coupons/validate for that — and it does not list automatic promotions, which live at GET /v1/promotions.

GET /v1/coupons

Error

A valid request URL is required to generate request examples

200

{
  "items": [
    {
      "id": "cpn-7f3a91c2",
      "code": "SAVE10",
      "discount": {
        "type": "percentage",
        "rateBps": 1000
      },
      "validFrom": "2026-01-01T00:00:00.000Z",
      "validUntil": "2026-12-31T23:59:59.000Z",
      "maxRedemptions": 5,
      "minBasketCents": 0,
      "active": true,
      "redemptionCount": 0
    }
  ],
  "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

Response

200

application/json

A page of coupons, each with its active flag and ledger redemption count.

A page of coupons, each with its active flag and ledger redemption count.

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