Loyalty

Parameters

• idpath · string · uuid

  Required

  UUIDv7 of the resource.

  For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.

Responses

• 200

  The guest's balance and statement.

  LoyaltyAccount · application/json

  • balance_pointsinteger · int64

    Required

    Points available to spend now: the sum of every movement, so an expired earn is already taken off by the expire that wrote it off rather than filtered out here.

  • customer_idstring · uuid

    Required

  • statementarray of LoyaltyMovement

    Required

    The guest's movements, newest first, bounded to the most recent 50.

    • idstring · uuid

      Required

    • typestring · enum

      Required

      Why the balance moved, never which way. earn a sale earned points; redeem points paid for something; adjust a person credited or debited them by hand, with a note saying why; expire what was left of one earn was written off when its term ran out; reverse a sale that earned or spent points was voided, so the movement came back.

      earnredeemadjustexpirereverse

    • created_atTimestamp

      RequiredRead only

      Server-assigned RFC 3339 timestamp, always UTC.

      Server-assigned because device clocks drift and cannot be trusted for ordering — a till that has been powered off for a week may come back with a clock hours out. Where the device's own view of time matters it is carried separately in client_created_at.

    • expires_atTimestamp

      Nullable

      When this earn stops being worth anything, set at earn time from the programme's term. Null for a redemption, a reversal, and for an earn under a programme that never expires points.

    • location_idstring · uuid

      Nullable

      The site the movement's sale was rung at, so a liability can be attributed to the site that issued it. Null for a movement with no sale.

    • notestring

      Why a person made this adjustment. Empty for a movement from a sale.

    • order_idstring · uuid

      Nullable

      The sale this movement was part of, or null for one made by hand or by the expiry sweep.

    • pointsinteger · int64

      Required

      Signed. Negative for points spent or written off, positive for points added.

• 400

  The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

  Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

• 401

  No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

  Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

• 403

  Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

  Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

• 404

  No such resource, or none visible to this caller.

  Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

• 410

  The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

• 429

  Rate limit exceeded. Honour Retry-After rather than applying your own backoff.

  A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

• 500

  Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.

  The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

• 503

  Temporarily unable to serve the request — a dependency is down or the service is shedding load.

  Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

Parameters

• idpath · string · uuid

  Required

  UUIDv7 of the resource.

  For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.

Request body application/json · LoyaltyHoldBatchCreateRequest

• itemsarray of LoyaltyHoldBatchCreateItem

  Required

  ≥ 1 items · ≤ 10 items

  • idempotency_keyItemIdempotencyKey

    Required

    A key for one item in a batch, minted by the client when it queues the item and reused on every attempt to send it. The item, not the request, is the unit of work: a retried batch returns the stored result for every item already applied under its key. A fresh key per attempt defeats the whole mechanism.

    Scoped per merchant, so keys need only be unique within a merchant's own traffic.

    16–255 chars

  • loyalty_holdLoyaltyHoldCreate

    Required

    Holds a guest's points for a reward. The id is minted by the client, so retrying with the same id never holds twice.

    • idstring · uuid

      Required

      Minted by the client; a retry under the same id answers the same hold.

    • pointsinteger · int64

      Required

      The points the rewards being redeemed cost.

      ≥ 1

Responses

• 200

  The batch was processed. results says what happened to each item.

  BatchResponse · application/json

  • resultsarray of BatchResult

    Required

    • idstring · uuid

      The resource the item created or changed. Absent when it failed.

    • idempotency_keystring

      Required

      The item's key, echoed so a result can be matched by key as well as position.

    • problemProblem

      Nullable

      Why the item failed, as an RFC 9457 problem. A 422 means the item is malformed and will never succeed — drop it and show it to staff rather than retrying for ever. A 409 or a 5xx means try again later.

      • typestring · uri

        Required

        A stable URI identifying the problem kind. This is the field to branch on.

        default about:blank

      • api_versionstring

        Present on an api-version-retired or api-version-unknown refusal: the API-Version this server speaks (docs/decisions/0011).

      • detailstring

        A human-readable explanation specific to this occurrence. Safe to show to a developer; never contains internal state, SQL, or stack traces.

      • instancestring · uri-reference

        A URI reference identifying the specific occurrence.

      • invalid_paramsarray of InvalidParam

        Present on 422 responses. Lists every field that failed validation, rather than only the first, so a client can highlight an entire form in one pass.

        • codestring

          Stable machine-readable code for this failure, for clients that localise their own messages rather than showing reason.

        • pointerstring

          Required

          RFC 6901 JSON Pointer to the offending value within the request body. A pointer rather than a field name so that failures nested inside arrays — the third line item of an order — are addressable at all.

        • reasonstring

          Required

          Why this value was rejected, in human-readable form.

      • refusalsarray of Location refusal

        Present on 409 responses to a withdrawal refused by the state it depends on (deleting a location with tills still assigned, open orders, …). Lists every reason at once, each with how much stands in the way, so a client can say what to put right and link to it rather than walking a person through one refusal after another.

        • kindstring

          Required

          A stable refusal kind — devices, open_orders, drawer_sessions, bookings or stock — that a client links to the screen that puts it right. Branch on this field, never on the surrounding prose.

        • countinteger

          Required

          How many things stand in the way of the withdrawal, so a client can repeat the number rather than re-read prose.

          ≥ 1

      • statusinteger

        Required

        The HTTP status code, repeated here so the body is self-contained.

        100–599

      • titlestring

        Required

        A short, human-readable summary of the problem kind.

      • trace_idstring

        The OpenTelemetry trace id for this request. Quote it in a support ticket and the whole request can be pulled up.

    • statusstring · enum

      Required

      created — the item made a new resource. updated — it changed an existing one.

      unchanged — this key was already applied and the original outcome stands. A success, not an error: it is what a client retrying a batch it was unsure landed should expect, and it clears the item from its queue exactly as created does.

      failed — the item was refused, and nothing else in the batch was affected. See problem.

      createdupdatedunchangedfailed

    • versioninteger · int64

      The resource's version after the item. Absent when it failed.

• 400

  The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

  Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

• 401

  No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

  Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

• 403

  Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

  Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

• 410

  The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

• 415

  The request Content-Type is not supported. This API accepts application/json on all mutations.

• 422

  The request parsed but failed validation.

  invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.

  Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

• 429

  Rate limit exceeded. Honour Retry-After rather than applying your own backoff.

  A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

• 500

  Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.

  The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

• 503

  Temporarily unable to serve the request — a dependency is down or the service is shedding load.

  Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

Parameters

• idpath · string · uuid

  Required

  UUIDv7 of the resource.

  For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.

• hold_idpath · string · uuid

  Required

  UUIDv7 of the hold on the guest's points.

• Idempotency-Keyheader · string

  Required

  A client-generated key making this request safe to retry.

  Required on every mutation that creates a resource or moves money. A till on bad wifi cannot tell a lost response from a lost request; without a key its only options are to risk a duplicate sale or to drop a real one. With a key it retries freely: the first request to arrive is processed, and every replay returns that same stored response.

  Rules:

  • Mint the key once, when the operation is first queued, and reuse it for every retry. A fresh key per attempt defeats the mechanism entirely.
  • Keys are scoped per merchant and per operation, and are retained for 30 days — long enough that a till switched off mid-sync can retry with the same key however long it stayed on the shelf.
  • Replaying a key with a different request body is a client bug and is rejected with 422, rather than silently returning the first result — quietly serving the old response would hide a real inconsistency in the caller.

  A UUIDv7 or ULID is a good choice.

Request body application/json · LoyaltyHoldVoidRequest

Responses

• 200

  The hold was voided.

  LoyaltyHold · application/json

  • idstring · uuid

    Required

  • customer_idstring · uuid

    Required

  • expires_atstring · date-time

    Required

    When the hold stops counting against the guest if nothing has ended it.

  • pointsinteger · int64

    Required

    ≥ 1

  • statusstring · enum

    Required

    held until it ends. settled once the sale that redeemed the reward has spent it, voided once the till gave it back, and expired once expires_at passed with neither.

    heldsettledvoidedexpired

• 400

  The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

  Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

• 401

  No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

  Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

• 403

  Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

  Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

• 404

  No such resource, or none visible to this caller.

  Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

• 409

  The request conflicts with current state — a uniqueness constraint, or an attempt to mutate an order that is already completed or voided.

  Unlike 412, re-reading and retrying unchanged will not resolve it; the request itself has to change.

• 410

  The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

• 415

  The request Content-Type is not supported. This API accepts application/json on all mutations.

• 422

  The request parsed but failed validation.

  invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.

  Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

• 429

  Rate limit exceeded. Honour Retry-After rather than applying your own backoff.

  A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

• 500

  Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.

  The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

• 503

  Temporarily unable to serve the request — a dependency is down or the service is shedding load.

  Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

Request body application/json · LoyaltyAdjustmentBatchCreateRequest

• itemsarray of LoyaltyAdjustmentBatchCreateItem

  Required

  ≥ 1 items · ≤ 500 items

  • customer_idstring · uuid

    Required

    The guest whose balance moves. A guest of another merchant is refused.

  • idempotency_keyItemIdempotencyKey

    Required

    A key for one item in a batch, minted by the client when it queues the item and reused on every attempt to send it. The item, not the request, is the unit of work: a retried batch returns the stored result for every item already applied under its key. A fresh key per attempt defeats the whole mechanism.

    Scoped per merchant, so keys need only be unique within a merchant's own traffic.

    16–255 chars

  • location_idstring · uuid

    Nullable

    The site the adjustment is attributed to, the manager's chosen site, when they have one. Absent or null, the movement is reported as unattributed rather than dropped. A site of another merchant is refused.

  • notestring

    Required

    Why the adjustment was made, and required. It is stored on the movement so the ledger stays contestable — an unexplained credit is indistinguishable from an error, and a guest asking why their points changed deserves an answer.

    1–500 chars

  • pointsinteger · int64

    Required

    Signed: positive to credit, negative to debit. Zero is refused rather than recorded — a movement of nothing is a note somebody meant to attach to a real adjustment.

    The sign lives here and the reason in note, which is house rule 4: the kind of a movement says why and never which direction, so a balance stays SUM(points).

Responses

• 200

  The batch was processed. results says what happened to each item.

  BatchResponse · application/json

  • resultsarray of BatchResult

    Required

    • idstring · uuid

      The resource the item created or changed. Absent when it failed.

    • idempotency_keystring

      Required

      The item's key, echoed so a result can be matched by key as well as position.

    • problemProblem

      Nullable

      Why the item failed, as an RFC 9457 problem. A 422 means the item is malformed and will never succeed — drop it and show it to staff rather than retrying for ever. A 409 or a 5xx means try again later.

      • typestring · uri

        Required

        A stable URI identifying the problem kind. This is the field to branch on.

        default about:blank

      • api_versionstring

        Present on an api-version-retired or api-version-unknown refusal: the API-Version this server speaks (docs/decisions/0011).

      • detailstring

        A human-readable explanation specific to this occurrence. Safe to show to a developer; never contains internal state, SQL, or stack traces.

      • instancestring · uri-reference

        A URI reference identifying the specific occurrence.

      • invalid_paramsarray of InvalidParam

        Present on 422 responses. Lists every field that failed validation, rather than only the first, so a client can highlight an entire form in one pass.

        • codestring

          Stable machine-readable code for this failure, for clients that localise their own messages rather than showing reason.

        • pointerstring

          Required

          RFC 6901 JSON Pointer to the offending value within the request body. A pointer rather than a field name so that failures nested inside arrays — the third line item of an order — are addressable at all.

        • reasonstring

          Required

          Why this value was rejected, in human-readable form.

      • refusalsarray of Location refusal

        Present on 409 responses to a withdrawal refused by the state it depends on (deleting a location with tills still assigned, open orders, …). Lists every reason at once, each with how much stands in the way, so a client can say what to put right and link to it rather than walking a person through one refusal after another.

        • kindstring

          Required

          A stable refusal kind — devices, open_orders, drawer_sessions, bookings or stock — that a client links to the screen that puts it right. Branch on this field, never on the surrounding prose.

        • countinteger

          Required

          How many things stand in the way of the withdrawal, so a client can repeat the number rather than re-read prose.

          ≥ 1

      • statusinteger

        Required

        The HTTP status code, repeated here so the body is self-contained.

        100–599

      • titlestring

        Required

        A short, human-readable summary of the problem kind.

      • trace_idstring

        The OpenTelemetry trace id for this request. Quote it in a support ticket and the whole request can be pulled up.

    • statusstring · enum

      Required

      created — the item made a new resource. updated — it changed an existing one.

      unchanged — this key was already applied and the original outcome stands. A success, not an error: it is what a client retrying a batch it was unsure landed should expect, and it clears the item from its queue exactly as created does.

      failed — the item was refused, and nothing else in the batch was affected. See problem.

      createdupdatedunchangedfailed

    • versioninteger · int64

      The resource's version after the item. Absent when it failed.

• 400

  The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

  Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

• 401

  No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

  Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

• 403

  Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

  Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

• 410

  The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

• 415

  The request Content-Type is not supported. This API accepts application/json on all mutations.

• 422

  The request parsed but failed validation.

  invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.

  Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

• 429

  Rate limit exceeded. Honour Retry-After rather than applying your own backoff.

  A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

• 500

  Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.

  The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

• 503

  Temporarily unable to serve the request — a dependency is down or the service is shedding load.

  Retry with the same Idempotency-Key after Retry-After. This is always safe: a request that did take effect before the failure will be recognised as a replay.

Parameters

• Idempotency-Keyheader · string

  Required

  A client-generated key making this request safe to retry.

  Required on every mutation that creates a resource or moves money. A till on bad wifi cannot tell a lost response from a lost request; without a key its only options are to risk a duplicate sale or to drop a real one. With a key it retries freely: the first request to arrive is processed, and every replay returns that same stored response.

  Rules:

  • Mint the key once, when the operation is first queued, and reuse it for every retry. A fresh key per attempt defeats the mechanism entirely.
  • Keys are scoped per merchant and per operation, and are retained for 30 days — long enough that a till switched off mid-sync can retry with the same key however long it stayed on the shelf.
  • Replaying a key with a different request body is a client bug and is rejected with 422, rather than silently returning the first result — quietly serving the old response would hide a real inconsistency in the caller.

  A UUIDv7 or ULID is a good choice.

Request body application/json · LoyaltyExpiryCreate

• inactivity_expire_daysinteger

  Required

  ≥ 1

Responses

• 201

  What was written off.

  LoyaltyExpiry · application/json

  • customersinteger

    Required

    How many guests' balances were written off.

    ≥ 0

  • inactivity_expire_daysinteger

    Required

• 400

  The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

  Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

• 401

  No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

  Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

• 403

  Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

  Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

• 409

  The request conflicts with current state — a uniqueness constraint, or an attempt to mutate an order that is already completed or voided.

  Unlike 412, re-reading and retrying unchanged will not resolve it; the request itself has to change.

• 410

  The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

• 415

  The request Content-Type is not supported. This API accepts application/json on all mutations.

• 422

  The request parsed but failed validation.

  invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.

  Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

• 429

  Rate limit exceeded. Honour Retry-After rather than applying your own backoff.

  A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

• 500

  Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.

  The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Responses

• 200

  The programme.

  LoyaltyProgram · application/json

  • activeboolean

    Required

  • inactivity_expire_daysinteger

    RequiredNullable

    How long a guest may go without earning before their whole balance is written off; null for never.

    ≥ 1

  • inheritedboolean

    RequiredRead only

    Whether this is the brand's programme a franchisee runs under until it saves one of its own.

  • location_idsarray of string · uuid

    Required

    The sites the programme runs at. Empty is every site.

  • offline_redemption_cap_pointsinteger · int64

    The most points one offline redemption may spend; the till honours the lesser of the guest's balance as it last saw it and this cap. Zero turns offline redemption off.

    ≥ 0

  • points_expire_daysinteger

    RequiredNullable

    How long each earned point lasts on a points programme; null when points do not expire.

    ≥ 1

  • ratesarray of LoyaltyRate

    Required

    A points programme's earn and redeem rates, one per currency a site trades in.

    • point_valueMoney

      Required

      A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.

      The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.

      Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

      • amountinteger · int64

        Required

        The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

      • currencyCurrency

        Required

        ISO 4217 currency code.

        Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.

        One of 182 values; see the schema.

    • pointsinteger · int64

      Required

      The points earned for every whole spend. Zero earns nothing.

      ≥ 0

    • spendMoney

      Required

      A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.

      The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.

      Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

      • amountinteger · int64

        Required

        The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

      • currencyCurrency

        Required

        ISO 4217 currency code.

        Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.

        One of 182 values; see the schema.

  • rulestring · enum

    Required

    points earns on spend and redeems for rewards; visits is a stamp card granting visit_reward_id.

    pointsvisits

  • stamps_requiredinteger

    RequiredNullable

    The stamps a visits programme's card needs; null on a points programme.

    ≥ 2

  • tiersarray of LoyaltyTier

    Required

    ≤ 10 items

    • idstring · uuid

      Required

    • namestring

      Required

    • earn_rate_percentageRelativePercentage

      A percentage that may be negative or above 100, such as a change on a period before or a multiplier, in a decimal string with at most four decimal places: a fall of an eighth is "-12.5", and one and a half times is "150". Read and computed as a Percentage is, in parts per million.

      pattern ^-?(0|[1-9][0-9]{0,8})(\.[0-9]{1,4})?$

    • threshold_spendMoney

      A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.

      The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.

      Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

      • amountinteger · int64

        Required

        The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

      • currencyCurrency

        Required

        ISO 4217 currency code.

        Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.

        One of 182 values; see the schema.

    • threshold_visitsinteger · int64

      The number of completed linked orders that reaches the tier.

    • window_daysinteger · int32
  • versionVersion

    RequiredRead only

    Optimistic concurrency version, raised by the server on every write. A version is never lower than one already returned for the resource, though it may rise by more than one.

    Returned in the ETag response header as well as in the body. Send it back in If-Match on an update and the write is rejected with 412 if anyone else has written since — which is what stops two tills silently overwriting each other's edit to the same product when both come back online at once.

    ≥ 1

  • visit_reward_idstring · uuid

    RequiredNullable

    The reward a full stamp card grants; null on a points programme.

• 400

  The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

  Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

• 401

  No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

  Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

• 403

  Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

  Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

• 410

  The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

• 429

  Rate limit exceeded. Honour Retry-After rather than applying your own backoff.

  A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

• 500

  Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.

  The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Parameters

• If-Matchheader · string

  Required

  The ETag from the read that produced the value you are updating.

  Required on updates, not optional, because "last write wins" is the wrong default for a catalogue two managers might edit at once. If anything has been written since your read, the request is rejected with 412 and you re-read and re-apply.

  Use * to mean "write regardless of current version" — an explicit, greppable override rather than the silent default.

Request body application/merge-patch+json · LoyaltyProgramPatch

• activeboolean
• inactivity_expire_daysinteger · int32

  Nullable

  How long a guest may go without earning before their whole balance is written off; null for never.

  ≥ 1

• location_idsarray of string · uuid

  The sites the programme runs at. Empty is every site.

• offline_redemption_cap_pointsinteger · int64

  ≥ 0

• points_expire_daysinteger

  Nullable

  How long each earned point lasts on a points programme; null when points do not expire.

  ≥ 1

• ratesarray of LoyaltyRate

  A points programme's earn and redeem rates, one per currency a site trades in.

  • point_valueMoney

    Required

    A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.

    The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.

    Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

    • amountinteger · int64

      Required

      The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

    • currencyCurrency

      Required

      ISO 4217 currency code.

      Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.

      One of 182 values; see the schema.

  • pointsinteger · int64

    Required

    The points earned for every whole spend. Zero earns nothing.

    ≥ 0

  • spendMoney

    Required

    A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.

    The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.

    Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

    • amountinteger · int64

      Required

      The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

    • currencyCurrency

      Required

      ISO 4217 currency code.

      Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.

      One of 182 values; see the schema.

• rulestring · enum

  points earns on spend and redeems for rewards; visits is a stamp card granting visit_reward_id.

  pointsvisits

• stamps_requiredinteger

  Nullable

  The stamps a visits programme's card needs; null on a points programme.

  ≥ 2

• tiersarray of LoyaltyTierWrite

  ≤ 10 items

  • idstring · uuid

    RequiredNullable

    The tier's id; null for a tier being added, which is given one.

  • namestring

    Required

    1–64 chars

  • earn_rate_percentageRelativePercentage

    Required

    A percentage that may be negative or above 100, such as a change on a period before or a multiplier, in a decimal string with at most four decimal places: a fall of an eighth is "-12.5", and one and a half times is "150". Read and computed as a Percentage is, in parts per million.

    pattern ^-?(0|[1-9][0-9]{0,8})(\.[0-9]{1,4})?$

  • threshold_spendMoney

    RequiredNullable

    The spend that reaches the tier, or null for a tier reached by visits.

    • amountinteger · int64

      Required

      The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

    • currencyCurrency

      Required

      ISO 4217 currency code.

      Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.

      One of 182 values; see the schema.

  • threshold_visitsinteger

    RequiredNullable

    The visits that reach the tier, or null for a tier reached by spend.

    ≥ 1

  • window_daysinteger · int32

    Required

    ≥ 1

• visit_reward_idstring · uuid

  Nullable

  The reward a full stamp card grants; null on a points programme.

Responses

• 200

  The programme as saved.

  LoyaltyProgram · application/json

  • activeboolean

    Required

  • inactivity_expire_daysinteger

    RequiredNullable

    How long a guest may go without earning before their whole balance is written off; null for never.

    ≥ 1

  • inheritedboolean

    RequiredRead only

    Whether this is the brand's programme a franchisee runs under until it saves one of its own.

  • location_idsarray of string · uuid

    Required

    The sites the programme runs at. Empty is every site.

  • offline_redemption_cap_pointsinteger · int64

    The most points one offline redemption may spend; the till honours the lesser of the guest's balance as it last saw it and this cap. Zero turns offline redemption off.

    ≥ 0

  • points_expire_daysinteger

    RequiredNullable

    How long each earned point lasts on a points programme; null when points do not expire.

    ≥ 1

  • ratesarray of LoyaltyRate

    Required

    A points programme's earn and redeem rates, one per currency a site trades in.

    • point_valueMoney

      Required

      A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.

      The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.

      Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

      • amountinteger · int64

        Required

        The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

      • currencyCurrency

        Required

        ISO 4217 currency code.

        Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.

        One of 182 values; see the schema.

    • pointsinteger · int64

      Required

      The points earned for every whole spend. Zero earns nothing.

      ≥ 0

    • spendMoney

      Required

      A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.

      The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.

      Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

      • amountinteger · int64

        Required

        The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

      • currencyCurrency

        Required

        ISO 4217 currency code.

        Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.

        One of 182 values; see the schema.

  • rulestring · enum

    Required

    points earns on spend and redeems for rewards; visits is a stamp card granting visit_reward_id.

    pointsvisits

  • stamps_requiredinteger

    RequiredNullable

    The stamps a visits programme's card needs; null on a points programme.

    ≥ 2

  • tiersarray of LoyaltyTier

    Required

    ≤ 10 items

    • idstring · uuid

      Required

    • namestring

      Required

    • earn_rate_percentageRelativePercentage

      A percentage that may be negative or above 100, such as a change on a period before or a multiplier, in a decimal string with at most four decimal places: a fall of an eighth is "-12.5", and one and a half times is "150". Read and computed as a Percentage is, in parts per million.

      pattern ^-?(0|[1-9][0-9]{0,8})(\.[0-9]{1,4})?$

    • threshold_spendMoney

      A monetary amount in a specific currency: Square's Money, and Stripe's amount beside its currency.

      The amount is always an integer count of the currency's minor unit — pence for GBP, cents for USD. Zero-decimal currencies such as JPY have a minor unit equal to their major unit, so {"amount": 500, "currency": "JPY"} is ¥500 while {"amount": 500, "currency": "GBP"} is £5.00.

      Floating point is never used for money anywhere in this API. Binary floats cannot represent most decimal fractions exactly, so accumulating them across the line items of an order produces totals that disagree with the printed receipt by a penny. Integer minor units make every arithmetic operation exact.

      • amountinteger · int64

        Required

        The amount, as a whole number of the currency's minor unit. May be negative to express a refund, discount or credit.

      • currencyCurrency

        Required

        ISO 4217 currency code.

        Determines the minor unit that Money.amount is expressed in. Zero-decimal currencies such as JPY have a minor unit equal to the major unit.

        One of 182 values; see the schema.

    • threshold_visitsinteger · int64

      The number of completed linked orders that reaches the tier.

    • window_daysinteger · int32
  • versionVersion

    RequiredRead only

    Optimistic concurrency version, raised by the server on every write. A version is never lower than one already returned for the resource, though it may rise by more than one.

    Returned in the ETag response header as well as in the body. Send it back in If-Match on an update and the write is rejected with 412 if anyone else has written since — which is what stops two tills silently overwriting each other's edit to the same product when both come back online at once.

    ≥ 1

  • visit_reward_idstring · uuid

    RequiredNullable

    The reward a full stamp card grants; null on a points programme.

• 400

  The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

  Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

• 401

  No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

  Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

• 403

  Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

  Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

• 409

  The request conflicts with current state — a uniqueness constraint, or an attempt to mutate an order that is already completed or voided.

  Unlike 412, re-reading and retrying unchanged will not resolve it; the request itself has to change.

• 410

  The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

• 412

  The If-Match version did not match the resource's current version: someone else wrote since you read.

  This is the expected, healthy outcome of two clients editing the same record — not an error condition to suppress. Re-read the resource, re-apply your change on top of the new state, and retry with the fresh ETag.

• 415

  The request Content-Type is not supported. This API accepts application/json on all mutations.

• 422

  The request parsed but failed validation.

  invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.

  Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

• 429

  Rate limit exceeded. Honour Retry-After rather than applying your own backoff.

  A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

• 500

  Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.

  The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Parameters

• cursorquery · string

  Opaque cursor from a previous page's next_cursor. Omit to start from the beginning.

  Pass it back exactly as received. It is base64 and its structure is not part of this contract — decoding it, or constructing one by hand, will break without notice.

• limitquery · integer · int32

  Maximum items to return. The server may return fewer, so always drive the loop from has_more rather than from the size of the page you got back.

Responses

• 200

  The rewards.

  LoyaltyRewardPage · application/json

  • has_moreboolean

    Required

  • itemsarray of LoyaltyReward

    Required

    • idstring · uuid

      Required

    • namestring

      Required

    • activeboolean

      Required

    • cost_pointsinteger

      Required

      ≥ 1

    • discount_idstring · uuid

      Required

    • versionVersion

      RequiredRead only

      Optimistic concurrency version, raised by the server on every write. A version is never lower than one already returned for the resource, though it may rise by more than one.

      Returned in the ETag response header as well as in the body. Send it back in If-Match on an update and the write is rejected with 412 if anyone else has written since — which is what stops two tills silently overwriting each other's edit to the same product when both come back online at once.

      ≥ 1

  • next_cursorstring

    Nullable

• 400

  The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

  Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

• 401

  No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

  Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

• 403

  Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

  Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

• 410

  The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

• 422

  The request parsed but failed validation.

  invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.

  Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

• 429

  Rate limit exceeded. Honour Retry-After rather than applying your own backoff.

  A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

• 500

  Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.

  The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Parameters

• Idempotency-Keyheader · string

  Required

  A client-generated key making this request safe to retry.

  Required on every mutation that creates a resource or moves money. A till on bad wifi cannot tell a lost response from a lost request; without a key its only options are to risk a duplicate sale or to drop a real one. With a key it retries freely: the first request to arrive is processed, and every replay returns that same stored response.

  Rules:

  • Mint the key once, when the operation is first queued, and reuse it for every retry. A fresh key per attempt defeats the mechanism entirely.
  • Keys are scoped per merchant and per operation, and are retained for 30 days — long enough that a till switched off mid-sync can retry with the same key however long it stayed on the shelf.
  • Replaying a key with a different request body is a client bug and is rejected with 422, rather than silently returning the first result — quietly serving the old response would hide a real inconsistency in the caller.

  A UUIDv7 or ULID is a good choice.

Request body application/json · LoyaltyRewardCreate

• namestring

  Required

  1–100 chars

• cost_pointsinteger

  Required

  ≥ 1

• discount_idstring · uuid

  Required

Responses

• 201

  The reward.

  LoyaltyReward · application/json

  • idstring · uuid

    Required

  • namestring

    Required

  • activeboolean

    Required

  • cost_pointsinteger

    Required

    ≥ 1

  • discount_idstring · uuid

    Required

  • versionVersion

    RequiredRead only

    Optimistic concurrency version, raised by the server on every write. A version is never lower than one already returned for the resource, though it may rise by more than one.

    Returned in the ETag response header as well as in the body. Send it back in If-Match on an update and the write is rejected with 412 if anyone else has written since — which is what stops two tills silently overwriting each other's edit to the same product when both come back online at once.

    ≥ 1

• 400

  The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

  Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

• 401

  No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

  Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

• 403

  Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

  Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

• 410

  The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

• 415

  The request Content-Type is not supported. This API accepts application/json on all mutations.

• 422

  The request parsed but failed validation.

  invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.

  Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

• 429

  Rate limit exceeded. Honour Retry-After rather than applying your own backoff.

  A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

• 500

  Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.

  The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Parameters

• idpath · string · uuid

  Required

  UUIDv7 of the resource.

  For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.

• If-Matchheader · string

  Required

  The ETag from the read that produced the value you are updating.

  Required on updates, not optional, because "last write wins" is the wrong default for a catalogue two managers might edit at once. If anything has been written since your read, the request is rejected with 412 and you re-read and re-apply.

  Use * to mean "write regardless of current version" — an explicit, greppable override rather than the silent default.

Request body application/merge-patch+json · LoyaltyRewardPatch

• activeboolean

  Required

  false withdraws the reward. true is refused.

Responses

• 200

  The reward.

  LoyaltyReward · application/json

  • idstring · uuid

    Required

  • namestring

    Required

  • activeboolean

    Required

  • cost_pointsinteger

    Required

    ≥ 1

  • discount_idstring · uuid

    Required

  • versionVersion

    RequiredRead only

    Optimistic concurrency version, raised by the server on every write. A version is never lower than one already returned for the resource, though it may rise by more than one.

    Returned in the ETag response header as well as in the body. Send it back in If-Match on an update and the write is rejected with 412 if anyone else has written since — which is what stops two tills silently overwriting each other's edit to the same product when both come back online at once.

    ≥ 1

• 400

  The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

  Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

• 401

  No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

  Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

• 403

  Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

  Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

• 404

  No such resource, or none visible to this caller.

  Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

• 410

  The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

• 412

  The If-Match version did not match the resource's current version: someone else wrote since you read.

  This is the expected, healthy outcome of two clients editing the same record — not an error condition to suppress. Re-read the resource, re-apply your change on top of the new state, and retry with the fresh ETag.

• 415

  The request Content-Type is not supported. This API accepts application/json on all mutations.

• 422

  The request parsed but failed validation.

  invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.

  Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

• 429

  Rate limit exceeded. Honour Retry-After rather than applying your own backoff.

  A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

• 500

  Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.

  The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.

Responses

• 200

  The guests, one row each.

• 400

  The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).

  Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

• 401

  No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.

  Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

• 403

  Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.

  Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

• 410

  The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

• 422

  The request parsed but failed validation.

  invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.

  Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

• 429

  Rate limit exceeded. Honour Retry-After rather than applying your own backoff.

  A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

• 500

  Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.

  The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.