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

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

Promotions

Edit an existing coupon (code promo)

REPLACES the terms of one existing coupon addressed by the path id (server-minted; resolve it through GET /v1/coupons — the code is what customers type, the id is what this takes). The body is the SAME shape as create: it overwrites code, discount, the validity window, maxRedemptions and minBasketCents wholesale — a field you omit is not preserved, it is replaced by the schema’s value, so send the COMPLETE intended terms, not a partial patch. The path id is authoritative and the coupon’s own id never changes; there is no id in the body to retarget. Editing does NOT reset the redemption ledger: the returned view keeps the live redemptionCount, and a lowered maxRedemptions can already be at or below the count (the cap is enforced at redemption, not here). Only ACTIVE coupons are editable — a deactivated coupon is terminal and 404s, exactly as it reads back everywhere else. 404s when no active coupon bears the id.

PUT

coupons

{id}

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

{
  "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.

Path Parameters

string

required

The server-minted coupon id to act on (not the customer-facing code).

Minimum string length: 1

Body

application/json

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

Response

The edited coupon, still active, with its unchanged id and ledger 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

Preview a coupon against a basket total (code promo, bon de réduction)Deactivate a coupon (code promo)

Ventes & encaissement

Catalogue & stock

Finance

Clients & fidélité

Marketing & promotions

Services

Système

Other

Edit an existing coupon (code promo)

Authorizations

Path Parameters

Body

Response