Spoonity OffersView as markdown

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

4. Money and cart rules

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:

FieldTypeNotes
check_idstring, requiredYour 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_idstringLogged only.
pos_transaction_idstringLogged only on check.
customer_codestringThe 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.
customerobjectThe 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.
codesstring[]Coupon or promo codes entered or scanned.
selected_offer_idsstring[]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.
channelstringWhere 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).
linesarray, required{ line_id, sku, name?, price, quantity, categories?, modifiers?, discounts?, components?, metadata? }
discountsarrayDiscounts the POS already took off the whole check: [{ id, name?, amount }] (section 4).
subtotalinteger centsThe 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.
cashierobject{ id, name? }. Logged on check; sent to the loyalty program from close.
metadataobjectYour own fields, ignored by pricing (section 4).

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

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

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

5.2 POST /partners/pos/close

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

FieldTypeNotes
check_idrequiredSame as on check.
pos_transaction_idstring, requiredYour unique id for this closed transaction. The idempotency key.
terminal_idstringWhen it is 1 to 9 digits, the till number of the sale in the loyalty program; otherwise till 0.
cashierobject{ 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_codestringOptional, as on check: the scanned card number, the simple form of customer: { "customer_id": ... }. Send customer_code or customer, not both.
customerobjectOptional, 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.
metadataobjectYour own fields (section 4).
closed_atISO 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.linesarray, requiredThe 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.discountsarray, requiredThe 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.totalinteger cents, requiredThe receipt total before tax, after every discount. Posted to the loyalty program with the lines.
receipt.pos_discountsarrayYour own check-level discounts as applied, [{ id, name?, amount }]. Recorded; total already reflects them.
receipt.taxesarrayThe 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.tipinteger centsRecorded by Spoonity, not posted: the loyalty program has no field for it.
receipt.paymentsarray[{ method, amount }], method 1 to 64 characters. Recorded by Spoonity, not posted: the loyalty program has no field for it.
receipt.metadataobjectYour own fields (section 4).

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

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

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

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

{ "committed": false, "redemption_id": "ored_2b0f1c9e-5d0a-4c1e-9f1e-6f3a2d7c8b10", "evaluation_id": "S101:C-000814", "reason": "EVALUATION_EXPIRED", "state": "expired" }
reasonMeaning
NO_PENDING_EVALUATIONSpoonity 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_EXPIREDThe 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_CANCELLEDThe 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_BACKThe transaction was already voided.

5.3 POST /partners/pos/void

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

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

Response 200:

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

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

CallForwarded as
POST /partners/pos/quickpay/orderPOST /order
GET /partners/pos/quickpay/balance?card_number=<code>GET /quick-pay
POST /partners/pos/quickpay/voidPOST /order/void
{ "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

7. Timeouts and the fail-open rule

8. Errors

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

StatuscodeWhenPOS action
400INVALID_REQUESTBody 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.
401UNAUTHORIZEDMissing 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.
404NOT_FOUNDA path that does not exist.Fix the integration.
413PAYLOAD_TOO_LARGEThe request body is over 256 KB.Fix the integration; proceed without discount.
429RATE_LIMITEDThe 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.
409CHECK_CLOSEDcheck for a check that already closed or was refunded.Use a new check_id for a new sale.
409CHECK_REOPEN_LIMITThe check has used all 10 of its evaluation ids (section 6).Use a new check_id.
409OFFERS_RESERVEDAnother 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.
503OFFERS_UNAVAILABLEPromotions, 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.
503CUSTOMER_LOOKUP_UNAVAILABLEA customer.qr_token (or the customer parameter of GET /offers) could not be resolved. Not available yet.Proceed without discount; always close.
503QUICKPAY_UNAVAILABLEQuick Pay only (section 5.5): the loyalty platform could not be reached or took over 8 seconds.Read the balance before asking again.
500INTERNALA 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:

StepCostHow it is kept small
Promotion catalogmemory readServed from a short (5 s) cache, stale-on-error; never a database read per check. Loyalty rewards come from the cached loyalty offer source.
Customertwo loyalty program calls, only when a member is identifiedGuests 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 policyone small read, when configuredRead once per check; a merchant with no saved policy costs nothing.
Engineabout 2 ms for a 50-line check against 30 offers, measured in-processPure integer arithmetic, no I/O. An automated test fails the build if that check takes 500 ms or more.
Reservationa few indexed reads and writesOne 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

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.