Error

A valid request URL is required to generate request examples

{
  "id": "disc-2026-04-17-0142",
  "scope": "ticket",
  "lineId": null,
  "basis": "percent",
  "baseCents": 3980,
  "amountCents": -398,
  "effectiveBps": 1000,
  "reason": "manual_markdown",
  "note": "Damaged packaging on the display unit",
  "actorId": "usr-manager-3",
  "at": "2026-04-17T14:32:05.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
  }
}

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

Promotions

Apply an authorised discount to a whole ticket

Applies a manager-authorised reduction to the WHOLE ticket and persists the traced record. This is the deliberate, one-off human decision — reach for it only when no automatic promotion or presented coupon covers the case, and never to reproduce an offer that should be a rule (POST /v1/promotions) or a code (POST /v1/coupons). You supply the id, which is the IDEMPOTENCY ANCHOR: a second post of the same id is rejected 409 rather than doubling the reduction, so generate one id per intended discount and retry with the same one. reason is a closed vocabulary (manual_markdown, promotional, loyalty_reward, damaged_goods, manager_goodwill) and note carries up to 280 characters of free-text justification. Express the reduction either as basis:'percent' with percentBps in BASIS POINTS (1000 = 10%) or basis:'amount' with amountCents in integer CENTS; the cart snapshot you pass is what the gross is computed from, and it is read, never mutated. The default policy caps a discount at 50% and at 50.00 € and refuses a reduction larger than the base — breaching any of those gives 422, which means ‘the request was well-formed but too deep’, not a malformed body. Applying a discount records it; it does not settle a sale, which stays POST /v1/checkout/finalize.

POST

discounts

ticket

Error

A valid request URL is required to generate request examples

{
  "id": "disc-2026-04-17-0142",
  "scope": "ticket",
  "lineId": null,
  "basis": "percent",
  "baseCents": 3980,
  "amountCents": -398,
  "effectiveBps": 1000,
  "reason": "manual_markdown",
  "note": "Damaged packaging on the display unit",
  "actorId": "usr-manager-3",
  "at": "2026-04-17T14:32:05.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
  }
}

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

Option 1
Option 2

string

required

Minimum string length: 1

reason

enum<string>

required

Available options:

manual_markdown,

promotional,

loyalty_reward,

damaged_goods,

manager_goodwill

cart

object

required

Show child attributes

basis

enum<string>

required

Available options:

percent

percentBps

integer

required

Required range: 1 <= x <= 10000

note

string

Maximum string length: 280

Response

The persisted discount record, with the valued signed reduction.

string

required

scope

enum<string>

required

Available options:

line,

ticket

lineId

string | null

required

basis

enum<string>

required

Available options:

percent,

amount

baseCents

integer

required

Required range: -9007199254740991 <= x <= 9007199254740991

amountCents

integer

required

Required range: -9007199254740991 <= x <= 9007199254740991

effectiveBps

integer

required

Required range: -9007199254740991 <= x <= 9007199254740991

reason

enum<string>

required

Available options:

manual_markdown,

promotional,

loyalty_reward,

damaged_goods,

manager_goodwill

actorId

string

required

string

required

note

string

Deactivate a coupon Get an applied discount by id

Ventes & encaissement

Catalogue & stock

Finance

Clients & fidélité

Marketing & promotions

Services

Système

Other

Apply an authorised discount to a whole ticket

Authorizations

Body

Response