Error

A valid request URL is required to generate request examples

{
  "id": "promo-threshold-tshirt",
  "type": "threshold",
  "validFrom": "2026-01-01T00:00:00.000Z",
  "validUntil": "2026-12-31T00:00:00.000Z"
}

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

Update an existing promotion rule

REPLACES one existing automatic promotion rule wholesale, addressed by the path id. Unlike POST /v1/promotions (which upserts), this NEVER creates: an unknown id 404s rather than minting a rule, so it is the safe verb when you mean to edit one that is already live. The path id is authoritative — any id in the body is overwritten, so you cannot retarget the edit onto another rule. Every other rule is a FULL REPLACE, exactly like the upsert: each field absent from your body is destroyed, including the reward mechanics, and the API exposes NO read-modify-write path (the reads return a six-field directory projection with no mechanics). Call this only when you already hold the rule’s complete definition; if you were asked to tweak a live rule and lack its full mechanics, STOP and ask rather than reconstruct plausible values. Pick type and express money as integer CENTS, percentages as BASIS POINTS (1000 = 10%); validUntil must not precede validFrom. To stop a rule instead of editing it, use POST /v1/promotions/{id}/deactivate.

PUT

promotions

{id}

Error

A valid request URL is required to generate request examples

{
  "id": "promo-threshold-tshirt",
  "type": "threshold",
  "validFrom": "2026-01-01T00:00:00.000Z",
  "validUntil": "2026-12-31T00:00:00.000Z"
}

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

Minimum string length: 1

Body

application/json

Option 1
Option 2
Option 3

string

required

Minimum string length: 1

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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

type

enum<string>

required

Available options:

bogo

buySkuId

string

required

Pattern: ^[0-9a-f]{64}$

buyQuantity

integer

required

Required range: 0 < x <= 9007199254740991

getSkuId

string

required

Pattern: ^[0-9a-f]{64}$

getQuantity

integer

required

Required range: 0 < x <= 9007199254740991

getDiscountBps

integer

required

Required range: 1 <= x <= 10000

Response

The replaced rule, echoed back with its validity window as ISO instants.

Option 1
Option 2
Option 3

The replaced rule, echoed back with its validity window as ISO instants.

string

required

Minimum string length: 1

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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

type

enum<string>

required

Available options:

bogo

buySkuId

string

required

Pattern: ^[0-9a-f]{64}$

buyQuantity

integer

required

Required range: 0 < x <= 9007199254740991

getSkuId

string

required

Pattern: ^[0-9a-f]{64}$

getQuantity

integer

required

Required range: 0 < x <= 9007199254740991

getDiscountBps

integer

required

Required range: 1 <= x <= 10000

Get a promotion by id Deactivate a promotion rule

Ventes & encaissement

Catalogue & stock

Finance

Clients & fidélité

Marketing & promotions

Services

Système

Other

Update an existing promotion rule

Authorizations

Path Parameters

Body

Response