# POS check integration (`/partners/pos`)

For integration engineers at a POS company whose loyalty model is "send us
the check, we send back the discount". The POS sends the whole check at pay
time, Spoonity Offers prices it, and the POS applies the result. The POS
never computes a discount itself.

Base URL: `https://offers.spoonity.com`. POS partners with a dedicated
integration profile have their own docs site; your Spoonity contact will
tell you if that applies to you.

The request examples on this page are valid requests, and the response
examples show the shapes the service returns. Section 10 lists what this surface does not do yet.

## 1. The flow in one paragraph

The cashier identifies the customer (a scanned loyalty card or an entered
phone number), or leaves the check as a guest. When the cashier presses pay,
the POS sends the full check to Spoonity (`POST /check`). Spoonity looks up
the customer, applies the merchant's promotion rules and any reward the POS
selected, reserves single-use rewards for 15 minutes, and returns the
discount: one subtotal amount plus the per-line detail. The POS applies it and
takes payment. When the check closes, the POS posts `POST /close`; Spoonity
commits the redemption. A refund posts `POST /void`. If Spoonity is slow or
down at pay time, the POS closes the check without a discount and still posts
`close`.

## 2. Identifying the customer

How the customer is identified at the till decides which of these applies.

### Members: card number or phone

The POS sends the scanned card number as `customer_code`, or the
phone number as `customer.phone`. `customer_code` is the simple form of
`customer: { "customer_id": ... }`; send one or the other, never both. Spoonity looks the member up in the
merchant's loyalty program and prices the check with the promotions that
member can have. To use one of the member's rewards, the POS also sends its
`offer_id` in `selected_offer_ids`.

Send the code exactly as scanned. When the merchant's POS recognises loyalty
codes by a fixed prefix, send the whole code as scanned, prefix included;
Spoonity removes the prefix (an exact, case-sensitive match, set per merchant
during setup) before it uses the code.

This needs the merchant's loyalty program to be connected to Spoonity Offers.
Spoonity does that during setup. For a merchant that is not connected, the
member's rewards are not returned and the check is priced with the
promotions open to everyone.

```
Customer              POS terminal                  Spoonity Offers          Spoonity loyalty
     | card or phone     |                              |                       |
     |------------------>| pay pressed: POST /check     |                       |
     |                   |   { customer, lines,         |                       |
     |                   |     selected_offer_ids }     |                       |
     |                   |----------------------------->| look up member ------>|
     |                   |                              | reprice, reserve      |
     |                   |<-----------------------------| subtotal_discount     |
     |                   | apply discount, take payment |                       |
     |                   | check closes: POST /close    |                       |
     |                   |----------------------------->| commit                |
     |                   |<-----------------------------| { committed: true }   |
```

### Guests and coupon codes

With no customer, the check is priced with the promotions open to everyone.
A coupon (printed, or a QR the POS reads locally) carries a code. There are
two ways to integrate it, and only the first lets Spoonity price and protect
the code:

1. **The POS sends the code with `check`** (`codes: ["WELCOME5"]`, no
   customer). Spoonity validates it, computes the discount, and counts the use
   at `close`, so per-day caps, budgets and single-use codes are enforced.
2. **The POS applies the discount itself and only posts `close`.** Spoonity
   then never saw the check: `close` answers `NO_PENDING_EVALUATION` and
   nothing is counted against the code. That is faster at the till, but a
   code can be reused without limit (a fraud exposure). We do
   not recommend it.

```
Guest / coupon        POS terminal                  Spoonity Offers
     | code              |                              |
     |------------------>| pay pressed: POST /check     |
     |                   |   { codes: ["WELCOME5"] }    |
     |                   |----------------------------->| validate, reprice, reserve
     |                   |<-----------------------------| subtotal_discount
     |                   | check closes: POST /close    |
     |                   |----------------------------->| commit (counts the use)
```

## 3. Authentication and addressing

- Base path: `/partners/pos` on the Spoonity Offers service.
- Header `Authorization: Bearer <key>` on every request
  (`X-Spoonity-POS-Key: <key>` is also accepted). The key determines the
  merchant and the store: nothing in the body or query names either, and
  there is no `store_id` field.
- Each store can use its own Spoonity API key. The first request with a
  store key Spoonity has not seen before is checked once with the loyalty
  program (it may take up to a few seconds); from then on it is accepted at
  once. The request runs for the store's merchant, so promotions, app picks
  and codes are the merchant's, and the store's sales are posted to the
  loyalty program under the store. A merchant-level key Spoonity issued
  works the same way, with the merchant as the store.
- A missing or unknown key, a store key that belongs to another merchant,
  and a key the loyalty program no longer accepts (deactivated, expired or
  deleted) are `401 UNAUTHORIZED`. A revoked key stays refused: replace it in
  the POS configuration with the store's current key. If a key cannot be
  checked because the loyalty program is down, the answer is
  `503 OFFERS_UNAVAILABLE`: close without a discount, and the next check
  tries again.
- `Content-Type: application/json`. Unknown fields are rejected with `400`,
  so a typo never silently drops a field. Fields of your own go in
  `metadata` (section 4).
- Every response carries `X-Spoonity-Api-Version: 2026-10-16`, the version
  of this contract (section 11).

## 4. Money and cart rules

- All money is **integer cents**: `1149` is $11.49. Decimals are a `400`.
- **Modifiers.** If the POS prices a modifier separately, send the item at
  its base `price` and list the modifier on the line with its own unit `price`
  and `quantity`: `{ id, name?, price, quantity, modifiers?, metadata? }`. If
  the POS rolls the modifier into the item price, send the item at the full
  price and send no `modifiers`. Both are valid. With rolled-in prices, a
  free-item reward also covers the modifiers in that price. A modifier's
  `quantity` is per unit of the line. A modifier may carry its own
  `modifiers` (a modifier of a modifier, up to 3 levels deep), whose
  `quantity` is per unit of their parent; Spoonity prices every level,
  multiplying quantities down the tree.
- `line_id` must be unique within a check. Echo the same ids on re-checks and
  on `close`.
- **Combos.** Send a combo as one line whose `price` is the combo price,
  with its parts in `components`: `[{ component_id, sku, name?, price,
  quantity, categories?, modifiers?, metadata? }]`. A part's `price` is its a la carte
  unit price; it is not charged, it only decides how Spoonity splits the
  combo price across the parts (the parts always add up to the combo price).
  `quantity` is per combo. Modifiers go on the part, never on the combo line.
  A discount on a part takes off at most that part's share of the combo
  price. `component_id` is unique within the combo, and every part unit
  counts toward the 2000-unit budget.
- Discounts the POS already applied to an item (employee, senior) go on the
  line as `discounts: [{ id, name?, amount, source? }]`, whole-line cents
  (`source` is `pos`, the default, or `external`). By default Spoonity **does
  not add its own item discount on top** of a line the POS has discounted
  (reason `LOCALLY_DISCOUNTED`). The merchant can relax that rule in their
  promotion policy.
- Discounts the POS already took off the **whole check** (a manager comp, a
  coupon that is not Spoonity's) go at the check root as
  `discounts: [{ id, name?, amount }]`. They lock no line: item discounts
  still apply.
- Either way, order-level discounts are computed on the total after your
  discounts, and Spoonity never takes off more than is left after them, so
  the same money is never discounted twice. Never send a discount as a
  negative-priced modifier: a negative amount is a `400`.
- **`metadata`.** Fields of your own that Spoonity does not use go in an
  optional `metadata` object on the check, any line, component or modifier,
  the close and its receipt: string keys of 1 to 64 characters, values that
  are a string (up to 256 characters), a number, a boolean or `null`, at most
  50 keys. Spoonity ignores it for pricing. Unknown fields anywhere else stay
  a `400`.
- Limits (a request over any of them is a `400`):
  - 200 lines per check, 2000 units per check, 1 to 1000 units per line
    (`quantity` 0 is not allowed; leave the line off).
  - Any single amount at most 100,000,000 cents ($1,000,000), never negative.
  - Per line: at most 50 `categories`, 50 `discounts` and 50 `components`.
  - Per line, or per component on a combo: at most 50 modifiers counting
    every level, nested at most 3 deep. Each modifier's `quantity` is 1 to
    1000, and a nested modifier's quantity times its parents' is at most
    1000. Modifier units do not count toward the 2000.
  - At most 50 `codes`, 50 `selected_offer_ids` and 50 check `discounts`.
  - `check_id` is 1 to 60 characters. Other ids (`line_id`,
    `sku`, `component_id`, category, modifier and discount ids, codes,
    `terminal_id`, `pos_transaction_id`, `customer_id`) are 1 to 128
    characters; `name` fields at most 256. `phone` is 3 to 32 characters,
    `qr_token` 1 to 512. `cashier.id` and `cashier.name` are 1 to 50.
  - On `close`, `receipt.lines` follows the same rules as `check`,
    `receipt.discounts` holds at most 200 entries, and `receipt.pos_discounts`
    and `receipt.payments` at most 50 each.

## 5. Endpoints

### 5.1 `POST /partners/pos/check`

Send at pay time. Send again whenever the cart changes after that; each call
replaces the previous reservation for the same check.

Request:

| Field | Type | Notes |
|---|---|---|
| `check_id` | string, required | Your check number. Letters, digits, `_ . -`, at most 60, **no colon**. Must be unique per store for as long as the check can be refunded. If your check numbers reset daily, prefix them with the business date, for example `20260929-1042`. |
| `terminal_id` | string | Logged only. |
| `pos_transaction_id` | string | Logged only on `check`. |
| `customer_code` | string | The scanned card number, 1 to 128 characters. The simple form of `customer: { "customer_id": ... }`: it behaves exactly the same. Send `customer_code` or `customer`, not both (`400 INVALID_REQUEST`). Omit both for a guest. |
| `customer` | object | The alternative to `customer_code`: exactly one of `customer_id` (the scanned card number), `phone`, or `qr_token` (a customer app QR token; not available yet, it answers `503 CUSTOMER_LOOKUP_UNAVAILABLE`). Omit for a guest. |
| `codes` | string[] | Coupon or promo codes entered or scanned. |
| `selected_offer_ids` | string[] | The `offer_id` of each reward or promotion the customer wants to use. An offer that needs selecting and is not listed here is returned as `applicable`, not applied. |
| `channel` | string | Where the order was taken. Default `pos`. Free-form; recommended values `pos`, `dine_in`, `takeout`, `drive_thru`, `delivery`, `kiosk`. A promotion can be limited to channels (`CHANNEL_NOT_ELIGIBLE` elsewhere). |
| `lines` | array, required | `{ line_id, sku, name?, price, quantity, categories?, modifiers?, discounts?, components?, metadata? }` |
| `discounts` | array | Discounts the POS already took off the whole check: `[{ id, name?, amount }]` (section 4). |
| `subtotal` | integer cents | The POS's own subtotal for the check: the sum of its items and modifiers before any discount and before tax, in integer cents. Spoonity still prices from `lines` and never from this number. It is a cross-check: when it differs from the `subtotal` Spoonity computes, the response carries `subtotal_mismatch`, which catches mapping mistakes such as modifiers counted twice or a missing line. A mismatch is never an error. |
| `cashier` | object | `{ id, name? }`. Logged on `check`; sent to the loyalty program from `close`. |
| `metadata` | object | Your own fields, ignored by pricing (section 4). |

Worked example (a member identified by card number, using one reward, after
the cashier added a drink):

```json
{
  "check_id": "C-000812",
  "terminal_id": "T2",
  "customer_code": "6040123412341234",
  "selected_offer_ids": ["reward_free_side"],
  "lines": [
    { "line_id": "1", "sku": "combo_chicken", "name": "Chicken Combo", "price": 1149, "quantity": 1 },
    { "line_id": "2", "sku": "side_fries", "name": "Fries", "price": 399, "quantity": 1 },
    { "line_id": "3", "sku": "drink_fountain", "name": "Fountain Drink", "price": 279, "quantity": 1 }
  ]
}
```

Response `200`:

```json
{
  "evaluation_id": "S101:C-000812",
  "check_id": "C-000812",
  "customer": {
    "customer_id": "2114003",
    "balances": [{ "currency_id": "2974", "balance": 4200 }]
  },
  "subtotal": 1827,
  "subtotal_discount": 539,
  "total": 1288,
  "discounts": [
    { "pos_reference": "SPN-FREESIDE", "offer_id": "reward_free_side", "name": "Free Side (reward)",
      "amount": 399, "scope": "item", "line_id": "2", "unit_index": 0, "quantity": 1, "unit_amount": 399 },
    { "pos_reference": "SPN-HALFDRINK", "offer_id": "promo_half_drink", "name": "Half-price fountain drink",
      "amount": 140, "scope": "item", "line_id": "3", "unit_index": 0, "quantity": 1, "unit_amount": 140 }
  ],
  "offers": [
    { "offer_id": "reward_free_side", "name": "Free Side (reward)", "status": "applied",
      "source": { "type": "redemption", "vendor_perk_redemption_id": 501 },
      "pos_reference": "SPN-FREESIDE", "discount_total": 399 },
    { "offer_id": "promo_half_drink", "name": "Half-price fountain drink", "status": "applied",
      "source": { "type": "promotion_code" }, "pos_reference": "SPN-HALFDRINK", "discount_total": 140 }
  ],
  "receipt_lines": ["Free Side (reward) applied, you saved $3.99", "Half-price fountain drink applied, you saved $1.40"],
  "redemption_id": "ored_9d5bdcf1-1718-40ef-8b3d-0b50821b2a2e",
  "hold_expires_at": "2026-09-29T17:45:00.000Z"
}
```

What to do with it:

- **If the POS can only take one number**, apply `subtotal_discount` as a
  subtotal discount. That is the whole Spoonity discount, order and item
  combined.
- **If the POS applies discounts to items** (for example for tax), apply each
  `discounts[]` entry: a `scope: "item"` entry on its `line_id` (and
  `component_id` for a part of a combo), and a `scope: "order"` entry through
  its `allocations`, one `{ line_id, component_id?, amount }` per line, which
  add up to the discount's `amount`. All entries sum to `subtotal_discount`.
- **Quantities above 1.** An entry's `amount` (and an allocation's) is the
  total for the units it covers: apply it once to the line or part. An item
  entry's `quantity` is the units it covers. `unit_amount` is that amount
  divided by the units covered (an item entry's `quantity`; all the units of
  the line, or of the part, for an allocation), present only when it divides
  evenly. If your POS multiplies an item modifier by the line quantity,
  apply `unit_amount` instead, or send units that get different discounts as
  separate lines.
- `total` is `subtotal` minus your own line and check discounts
  (`external_discount_total`, present when you sent any) minus
  `subtotal_discount`. Pre-tax: Spoonity does not compute tax.
- `subtotal_mismatch` (`{ received, computed }`, cents) appears only when you
  sent `subtotal` and it differs from Spoonity's `subtotal`. Pricing is
  unchanged; it points at a mapping mistake. Absent when they agree.
- `offers[]` explains every offer the merchant has: `applied`, `applicable`
  (would apply if selected), `skipped` or `inapplicable`, each with a
  machine-readable `reason.code` (`MIN_SPEND_NOT_MET`, `RESERVED`,
  `LOCALLY_DISCOUNTED`, ...) and a cashier-readable `reason.message`.
- `receipt_lines` are ready-to-print customer lines. Treat them as display
  text, not a contract: the engine's wording may change (today it separates
  the two halves with a dash character; the example above shows a comma).
- `customer` is `null` for a guest. For a member it carries the loyalty
  program's `customer_id` and, when the program reports them, `balances`:
  one entry per loyalty currency, keyed by its currency id, in hundredths (a
  balance of 42 is `4200`).
- If the member lookup fails, the check answers `503 OFFERS_UNAVAILABLE`
  rather than silently pricing a member as a guest. Close without a discount.
- `hold_expires_at`: single-use rewards are held for this check until then
  (15 minutes). If payment has not completed by then, send `check` again. A
  check that closes after it does not commit (`EVALUATION_EXPIRED`), even
  if nothing else has claimed the reward yet. "Closes" is judged by
  `closed_at` on `close` when you send it (see 5.2).
- `external_discount_total` appears only when you sent line or check
  `discounts`. `redemption_id` and `hold_expires_at` are always present.

### 5.2 `POST /partners/pos/close`

Send once the check is paid and closed, **always**, even when `check` failed
or timed out.

| Field | Type | Notes |
|---|---|---|
| `check_id` | required | Same as on `check`. |
| `pos_transaction_id` | string, required | Your unique id for this closed transaction. The idempotency key. |
| `terminal_id` | string | When it is 1 to 9 digits, the till number of the sale in the loyalty program; otherwise till 0. |
| `cashier` | object | `{ id, name? }`, each 1 to 50 characters. The cashier of the sale in the loyalty program (`name` defaults to the id); without it the sale names Spoonity Offers. |
| `customer_code` | string | Optional, as on `check`: the scanned card number, the simple form of `customer: { "customer_id": ... }`. Send `customer_code` or `customer`, not both. |
| `customer` | object | Optional, the alternative to `customer_code`, same shape and rules as on `check` (exactly one of `customer_id`, `phone`, `qr_token`; a code prefix is removed the same way). It names the customer the sale is posted to the loyalty program for when no earlier `check` for this check identified one (for example `check` timed out and the POS went ahead). When both identified one, the customer from `check` is used. It never changes the discounts or the commit. A `qr_token` here names no one. |
| `metadata` | object | Your own fields (section 4). |
| `closed_at` | ISO 8601 with an offset (`Z` or `+hh:mm`) | When the check closed, in the store's local time with its offset (`2026-09-29T17:36:10-04:00`). The 15-minute hold is judged at this time, so a check closed inside the hold commits even if `close` reaches Spoonity later. Accepted up to 24 hours in the past and 5 minutes in the future of Spoonity's clock; outside that, or when absent, the arrival time is used. Its local wall clock also dates the sale in the loyalty program; a `Z` time or one out of bounds leaves the sale dated on arrival there. |
| `receipt.lines` | array, required | The final lines, same shape and limits as on `check`. Spoonity does not reprice at close (it commits what the last `check` evaluated), but posts these lines to the loyalty program for points. |
| `receipt.discounts` | array, required | The **Spoonity** discounts you actually applied: `{ pos_reference, amount, name?, line_id?, component_id?, unit_amount? }`, echoed from `check` (an allocation copied as is is accepted; `unit_amount` is ignored, `amount` counts). Your own local discounts stay on the lines. Empty array if you applied none. The references and the sum of `amount` are compared with what `check` returned (see mismatch below). |
| `receipt.total` | integer cents, required | The receipt total before tax, after every discount. Posted to the loyalty program with the lines. |
| `receipt.pos_discounts` | array | Your own check-level discounts as applied, `[{ id, name?, amount }]`. Recorded; `total` already reflects them. |
| `receipt.taxes` | array | The taxes on the check, one entry per tax: `[{ id, name?, amount }]`. `id` is 1 to 64 characters and unique within the array, `name` up to 256 characters, `amount` integer cents, 0 or more. At most 20. Each entry is posted to the loyalty program as a tax of the sale; an `id` the loyalty program does not know is still recorded. There is no single `receipt.tax` field: sending one is a `400`. |
| `receipt.tip` | integer cents | Recorded by Spoonity, not posted: the loyalty program has no field for it. |
| `receipt.payments` | array | `[{ method, amount }]`, `method` 1 to 64 characters. Recorded by Spoonity, not posted: the loyalty program has no field for it. |
| `receipt.metadata` | object | Your own fields (section 4). |

Example (the check above, with the free side applied):

```json
{
  "check_id": "C-000812",
  "pos_transaction_id": "TXN-S101-20260929-0812",
  "terminal_id": "T2",
  "closed_at": "2026-09-29T17:36:10-04:00",
  "receipt": {
    "lines": [
      { "line_id": "1", "sku": "combo_chicken", "name": "Chicken Combo", "price": 1149, "quantity": 1 },
      { "line_id": "2", "sku": "side_fries", "name": "Fries", "price": 399, "quantity": 1 }
    ],
    "discounts": [{ "pos_reference": "SPN-FREESIDE", "amount": 399, "line_id": "2" }],
    "total": 1149
  }
}
```

Response `200`:

```json
{ "committed": true, "redemption_id": "ored_9d5bdcf1-1718-40ef-8b3d-0b50821b2a2e", "evaluation_id": "S101:C-000812" }
```

If what you applied differs from what `check` returned (different amount,
dropped or extra discount), Spoonity **still commits** (the money already left
the till) and reports it:

```json
{
  "committed": true,
  "redemption_id": "ored_7c97dff0-bbc1-4dbf-980d-681e48bd4ba5",
  "evaluation_id": "S101:C-000813",
  "mismatch": {
    "expected_pos_references": ["SPN-WELCOME5"],
    "received_pos_references": ["SPN-WELCOME5"],
    "expected_discount_total": 500,
    "received_discount_total": 400
  }
}
```

`committed: false` is still `200`, so the POS never retries it forever. Apart
from `NO_PENDING_EVALUATION` the body also carries `redemption_id`,
`evaluation_id` and the record's `state`:

```json
{ "committed": false, "redemption_id": "ored_2b0f1c9e-5d0a-4c1e-9f1e-6f3a2d7c8b10", "evaluation_id": "S101:C-000814", "reason": "EVALUATION_EXPIRED", "state": "expired" }
```

| `reason` | Meaning |
|---|---|
| `NO_PENDING_EVALUATION` | Spoonity never priced this check (it was down, or the POS timed out and proceeded). Nothing to commit. The body is `{ "committed": false, "redemption_id": null, "reason": "NO_PENDING_EVALUATION" }`. The sale is still posted for points when an earlier `check` for it carried the customer, or when the `close` carries `customer_code` or `customer`. |
| `EVALUATION_EXPIRED` | The 15-minute hold had lapsed when the check closed (`closed_at` within its bounds, else when `close` arrived), whether or not Spoonity had already released the hold in the background. The reward was not consumed. A check that closed inside the hold but arrives late still commits, unless another order has used the same single-use reward since. Re-send `check` before payment if a check sits that long. |
| `EVALUATION_CANCELLED` | The check was voided before it closed, or the last `check` answered `409 OFFERS_RESERVED` (it lost the race for a single-use reward three times, and the reservation it tried to make was cancelled). |
| `EVALUATION_ROLLED_BACK` | The transaction was already voided. |

### 5.3 `POST /partners/pos/void`

Refund or void of a closed transaction, or cancellation of an open check.

```json
{ "check_id": "C-000813", "pos_transaction_id": "TXN-S101-20260929-0813" }
```

Response `200`:

```json
{ "voided": true, "redemption_id": "ored_7c97dff0-bbc1-4dbf-980d-681e48bd4ba5", "evaluation_id": "S101:C-000813", "state": "rolled_back" }
```

A void restores single-use rewards and usage counts. `voided: true` means
nothing is held or consumed for this check any more, and `state` says why:
`rolled_back` (it had closed), `cancelled` (it was still open) or `expired`
(its hold had already lapsed, so there was nothing left to release). An
unknown check answers `{ "voided": false, "redemption_id": null, "reason": "NO_PENDING_EVALUATION" }`.
Voiding a closed check also reverses its sale in the loyalty program, once
the sale has been posted there. `terminal_id` is accepted and logged. Partial refunds are not supported on
this surface yet.

### 5.4 `GET /partners/pos/offers`

Optional. The promotions open to everyone at this store, for a cashier
prompt before the cart is final. Nothing is applied or reserved.
Code-gated offers are never listed. The store is the POS key's. `channel`
defaults to `pos`. Any other query parameter is a `400`. Looking up a
member's offers on this endpoint is not available yet (section 10): the
`customer` parameter (a customer app QR token) is accepted, but answers
`503 CUSTOMER_LOOKUP_UNAVAILABLE`.

```json
{
  "customer": null,
  "offers": [
    { "offer_id": "promo_half_drink", "name": "Half-price fountain drink", "pos_reference": "SPN-HALFDRINK",
      "effect_type": "percent_off", "auto_apply": true, "pre_selected": false }
  ]
}
```

An offer whose cart condition is not met yet carries a `needs` reason (for
example `MIN_SPEND_NOT_MET` with the shortfall).

### 5.5 `/partners/pos/quickpay/*`: paying with the app balance

Optional, for merchants whose customers hold a balance in the app. Three
calls, **forwarded to Spoonity's loyalty platform, whose reply (status and
body) is returned unchanged**. Offers adds no rules of its own: no sign check,
balance check, idempotency or error mapping.

| Call | Forwarded as |
|---|---|
| `POST /partners/pos/quickpay/order` | `POST /order` |
| `GET /partners/pos/quickpay/balance?card_number=<code>` | `GET /quick-pay` |
| `POST /partners/pos/quickpay/void` | `POST /order/void` |

- **Key.** The POS key is the store's Spoonity API key and is passed on to the
  loyalty platform. A key that is not one (a shared key configured in Offers
  only) answers `401 UNAUTHORIZED`.
- **`order` fields.** `card_number` (the scanned code, prefix included; Offers
  removes the prefix) and `amount` are the only fields Offers reads. `amount`
  is **signed integer cents**: positive loads, negative redeems, so `-1250`
  redeems 12.50 (sent on as `-12.5` dollars). A decimal or missing `amount`, or
  an empty `card_number`, is `400`. Every other field (`till`,
  `receipt_number`, `cashier` as `{ id, name }`, and anything else) is passed
  on as sent. Make `receipt_number` unique per attempt.
- **`void`.** `{ "receipt": <reference_number from the order reply> }`. It
  works only on the customer's most recent Quick Pay receipt.
- **Replies** are the loyalty platform's: `success`, `reference_number`,
  `receipt_data.lines`, `receipt_data.user.balances[]` (in dollars) and
  `error.errors[]` (`reason`, `message`). A refusal, such as a short balance
  (there is no partial approval), is HTTP 200 with `success: false`.
- **Failure.** No answer within 8 seconds, or a network error, is
  `503 QUICKPAY_UNAVAILABLE`. Read the balance before asking again.
- Same rate limit, body limit and `X-Spoonity-Api-Version` header as the other
  POS calls. Nothing is stored in Offers.

```json
{ "card_number": "SPN123456789", "amount": -1250, "till": 2, "receipt_number": "S101-C-000813-1", "cashier": { "id": 17, "name": "Dana" } }
```

The merchant-facing description, with a worked example, is in the Panasonic
integration guide (section "Paying with the app balance").

## 6. Idempotency rules

- `check` is safe to repeat. The same `check_id` from the same store's key always refers to
  the same reservation, and each call replaces it with the new cart's result.
  A re-check whose cart no longer qualifies releases the held reward.
- `close` is idempotent on `pos_transaction_id` within a check: a retry
  returns the same answer and never commits twice. Transaction ids only need
  to be unique per check, so two stores (or terminals) may reuse one. A second `close` for an already committed
  check with a different transaction id also reports `committed: true`
  without committing again.
- `void` is idempotent on `pos_transaction_id`. A void may reuse the close's
  transaction id; the two are tracked separately.
- A check that already closed cannot be re-checked (`409 CHECK_CLOSED`): a new
  sale needs a new `check_id`.
- A check whose hold expired, or that was voided while open, can be checked
  again. Spoonity then reserves it under a new evaluation id,
  `S101:C-000812:2`, and every later call on that check uses it automatically.
  You never need to send the evaluation id back; it is for support and logs.
- A check has 10 evaluation ids: the first reservation plus 9 more. Every
  expiry, open void and lost single-use race (each internal retry behind
  `409 OFFERS_RESERVED`, up to three per `check`) uses one. After that,
  `check` answers `409 CHECK_REOPEN_LIMIT`.

## 7. Timeouts and the fail-open rule

- Time `check` out at about **3 seconds**. On timeout, a `5xx`, or a network error,
  **close the check without a Spoonity discount**. Do not block the cashier.
- **Always send `close`**, even after a failed or skipped `check`. It is
  cheap, idempotent, and it is how Spoonity finds out a check happened.
- Retry `close` and `void` on `5xx` or network errors with backoff (for
  example 1 s, 5 s, 30 s, then store and forward). They are idempotent.
- Do not retry `check` more than once per attempt.
- Do not retry a `4xx`: it is a real answer. The one exception is
  `409 OFFERS_RESERVED`, which you may re-send once within the same attempt
  (section 8).

## 8. Errors

Error bodies are `{ "error": { "code": "...", "message": "..." } }`.

| Status | `code` | When | POS action |
|---|---|---|---|
| 400 | `INVALID_REQUEST` | Body or query failed validation (`issues[]` says where). Includes decimals in money, duplicate `line_id`, unknown fields, a colon in `check_id`, a `store_id` (the key names the store), two customer identifiers (including `customer_code` together with `customer`), any limit in section 4. | Fix the integration; do not retry. |
| 401 | `UNAUTHORIZED` | Missing or unknown POS key, a store key of another merchant, or a key the loyalty program no longer accepts. | Configuration problem; proceed without discount, and replace the key. |
| 404 | `NOT_FOUND` | A path that does not exist. | Fix the integration. |
| 413 | `PAYLOAD_TOO_LARGE` | The request body is over 256 KB. | Fix the integration; proceed without discount. |
| 429 | `RATE_LIMITED` | The key sent too many requests (default 20 per second, bursts of 60). `Retry-After` gives the seconds to wait. | Wait that long and retry; if it does not clear, proceed without discount. |
| 409 | `CHECK_CLOSED` | `check` for a check that already closed or was refunded. | Use a new `check_id` for a new sale. |
| 409 | `CHECK_REOPEN_LIMIT` | The check has used all 10 of its evaluation ids (section 6). | Use a new `check_id`. |
| 409 | `OFFERS_RESERVED` | Another check won the race for the same single-use reward three times in a row within this one request. Rare. Each lost attempt uses one of the check's evaluation ids. | Re-send `check` once, else proceed without discount. |
| 503 | `OFFERS_UNAVAILABLE` | Promotions, the merchant's policy or the database could not be read, or a new store key could not be checked with the loyalty program. That includes a database statement that runs past its timeout (2 s by default) or a full connection queue, so a stalled database answers quickly rather than hanging. | Proceed without discount; always `close`. On `close`/`void`, retry with backoff. |
| 503 | `CUSTOMER_LOOKUP_UNAVAILABLE` | A `customer.qr_token` (or the `customer` parameter of `GET /offers`) could not be resolved. Not available yet. | Proceed without discount; always `close`. |
| 503 | `QUICKPAY_UNAVAILABLE` | Quick Pay only (section 5.5): the loyalty platform could not be reached or took over 8 seconds. | Read the balance before asking again. |
| 500 | `INTERNAL` | A bug on our side. | Same as 503. |

## 9. Latency budget

Target: **under 300 ms p95** for `check`, measured at Spoonity. A 3 second POS
timeout leaves room for the network between the store and Spoonity, and for
a slow member lookup.

What the time is spent on, and what keeps it small:

| Step | Cost | How it is kept small |
|---|---|---|
| Promotion catalog | memory read | Served from a short (5 s) cache, stale-on-error; never a database read per check. Loyalty rewards come from the cached loyalty offer source. |
| Customer | two loyalty program calls, **only when a member is identified** | Guests and coupon checks make no loyalty call at all. A member lookup is normally well under a second; each call is cut off at 2.5 s and retried once on a timeout, network error or `5xx`. |
| Merchant policy | one small read, when configured | Read once per check; a merchant with no saved policy costs nothing. |
| Engine | about 2 ms for a 50-line check against 30 offers, measured in-process | Pure integer arithmetic, no I/O. An automated test fails the build if that check takes 500 ms or more. |
| Reservation | a few indexed reads and writes | One lookup for the check, usage reads only for offers that carry caps, one insert, one hold. Each database statement is capped at 2 s. |

We have not measured this end to end from a store yet. The network path
from your stores to Spoonity adds to these numbers.

## 10. What is not done yet

- **App reward picks are live.** A customer can pick a reward in the
  merchant's app, and the check applies it from the scanned code alone. The
  POS does not need to send the reward's `offer_id`. See the
  [app reward picks guide](app.md).
- **Member offers on `GET /offers`.** The endpoint lists the promotions open
  to everyone; it does not look up a member yet.
- **Points are posted from `close` where it is turned on.** When Spoonity
  has enabled the loyalty forward for the merchant, every `close` with an
  identified customer is posted to the loyalty program in the background
  (points, plus redemption of the loyalty rewards you applied), and voiding
  a closed check reverses it. `close` never waits for it. The customer is
  the one `check` identified, else the `customer_code` (or `customer`) sent on `close`; a check
  with neither is recorded but not posted. Where it is not
  enabled for a merchant, `close` commits the reward and discount usage in
  Offers only, and your integration also submits the order to the Spoonity
  loyalty platform's order endpoint for points. Ask Spoonity which applies
  to your merchant; never do both, or the sale is counted twice.
- **Partial refunds** are not exposed here.
- **One key per merchant**, not per store or terminal.

## 11. Versioning and compatibility

Every response from `/partners/pos` carries `X-Spoonity-Api-Version:
2026-10-16`, the version of the contract on this page. New fields may be
added to requests, and are always optional, so a valid request stays valid.
New fields may be added to responses; ignore the ones you do not know.
Nothing documented here is removed or changes meaning without a new
version.
