Error

A valid request URL is required to generate request examples

[
  {
    "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
  }
]

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "statusCode": 123,
    "fieldErrors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

Promotions

List the coupon catalogue

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 UNPAGINATED and returns a bare JSON array, so a large batch run comes back whole. 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

coupons

Error

A valid request URL is required to generate request examples

[
  {
    "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
  }
]

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "statusCode": 123,
    "fieldErrors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

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.

Response

Every coupon, with its active flag and its ledger redemption count.

string

required

Minimum string length: 1

code

string

required

Minimum string length: 1

discount

object

required

Option 1
Option 2

Show child attributes

validFrom

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

validUntil

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

maxRedemptions

integer

required

Required range: 0 < x <= 9007199254740991

minBasketCents

integer

required

Required range: 0 <= x <= 9007199254740991

active

boolean

required

redemptionCount

integer

required

Required range: 0 <= x <= 9007199254740991

Example:

[
  {
    "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
  }
]

Get a loyalty member by id Create one coupon under a chosen code

Ventes & encaissement

Catalogue & stock

Finance

Clients & fidélité

Marketing & promotions

Services

Système

Other

List the coupon catalogue

Authorizations

Response