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

Batch-generate a run of coupon codes

Mints count DISTINCT coupons (1–1000) that all share one discount, validity window, maxRedemptions and minBasketCents, each under a generated code optionally prefixed with codePrefix. Use it for one-per-customer mailing or compensation runs where the codes must not be guessable; use POST /v1/coupons when a single named code is what you want. The whole run is created inside one transaction and every minted coupon is returned in the reply — there is no later way to re-list just this batch, so keep the response (or filter GET /v1/coupons by your prefix). NOT idempotent: repeating the call mints a second run of fresh codes rather than returning the first.

POST

coupons

batch

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.

Body

application/json

count

integer

required

Required range: 0 < x <= 1000

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

codePrefix

string

Required string length: 1 - 32

Response

Every minted coupon, in creation order, each with its generated code.

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
  }
]

Create one coupon under a chosen code Preview a coupon against a basket total

Ventes & encaissement

Catalogue & stock

Finance

Clients & fidélité

Marketing & promotions

Services

Système

Other

Batch-generate a run of coupon codes

Authorizations

Body

Response