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:
- The POS sends the code with
check(codes: ["WELCOME5"], no customer). Spoonity validates it, computes the discount, and counts the use atclose, so per-day caps, budgets and single-use codes are enforced. - The POS applies the discount itself and only posts
close. Spoonity then never saw the check:closeanswersNO_PENDING_EVALUATIONand 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/poson 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 nostore_idfield. - 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 is503 OFFERS_UNAVAILABLE: close without a discount, and the next check tries again. Content-Type: application/json. Unknown fields are rejected with400, so a typo never silently drops a field. Fields of your own go inmetadata(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:
1149is $11.49. Decimals are a400. - Modifiers. If the POS prices a modifier separately, send the item at
its base
priceand list the modifier on the line with its own unitpriceandquantity:{ 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 nomodifiers. Both are valid. With rolled-in prices, a free-item reward also covers the modifiers in that price. A modifier'squantityis per unit of the line. A modifier may carry its ownmodifiers(a modifier of a modifier, up to 3 levels deep), whosequantityis per unit of their parent; Spoonity prices every level, multiplying quantities down the tree. line_idmust be unique within a check. Echo the same ids on re-checks and onclose.- Combos. Send a combo as one line whose
priceis the combo price, with its parts incomponents:[{ component_id, sku, name?, price, quantity, categories?, modifiers?, metadata? }]. A part'spriceis 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).quantityis 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_idis 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 (sourceispos, the default, orexternal). By default Spoonity does not add its own item discount on top of a line the POS has discounted (reasonLOCALLY_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 optionalmetadataobject 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 ornull, at most 50 keys. Spoonity ignores it for pricing. Unknown fields anywhere else stay a400.- Limits (a request over any of them is a
400):- 200 lines per check, 2000 units per check, 1 to 1000 units per line
(
quantity0 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, 50discountsand 50components. - Per line, or per component on a combo: at most 50 modifiers counting
every level, nested at most 3 deep. Each modifier's
quantityis 1 to 1000, and a nested modifier's quantity times its parents' is at most- Modifier units do not count toward the 2000.
- At most 50
codes, 50selected_offer_idsand 50 checkdiscounts. check_idis 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;namefields at most 256.phoneis 3 to 32 characters,qr_token1 to 512.cashier.idandcashier.nameare 1 to 50.- On
close,receipt.linesfollows the same rules ascheck,receipt.discountsholds at most 200 entries, andreceipt.pos_discountsandreceipt.paymentsat most 50 each.
- 200 lines per check, 2000 units per check, 1 to 1000 units per line
(
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):
{
"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:
- If the POS can only take one number, apply
subtotal_discountas 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: ascope: "item"entry on itsline_id(andcomponent_idfor a part of a combo), and ascope: "order"entry through itsallocations, one{ line_id, component_id?, amount }per line, which add up to the discount'samount. All entries sum tosubtotal_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'squantityis the units it covers.unit_amountis that amount divided by the units covered (an item entry'squantity; 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, applyunit_amountinstead, or send units that get different discounts as separate lines. totalissubtotalminus your own line and check discounts (external_discount_total, present when you sent any) minussubtotal_discount. Pre-tax: Spoonity does not compute tax.subtotal_mismatch({ received, computed }, cents) appears only when you sentsubtotaland it differs from Spoonity'ssubtotal. 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),skippedorinapplicable, each with a machine-readablereason.code(MIN_SPEND_NOT_MET,RESERVED,LOCALLY_DISCOUNTED, ...) and a cashier-readablereason.message.receipt_linesare 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).customerisnullfor a guest. For a member it carries the loyalty program'scustomer_idand, when the program reports them,balances: one entry per loyalty currency, keyed by its currency id, in hundredths (a balance of 42 is4200).- If the member lookup fails, the check answers
503 OFFERS_UNAVAILABLErather 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, sendcheckagain. A check that closes after it does not commit (EVALUATION_EXPIRED), even if nothing else has claimed the reward yet. "Closes" is judged byclosed_atonclosewhen you send it (see 5.2).external_discount_totalappears only when you sent line or checkdiscounts.redemption_idandhold_expires_atare 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):
{
"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" }
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.
{ "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.
| 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. orderfields.card_number(the scanned code, prefix included; Offers removes the prefix) andamountare the only fields Offers reads.amountis signed integer cents: positive loads, negative redeems, so-1250redeems 12.50 (sent on as-12.5dollars). A decimal or missingamount, or an emptycard_number, is400. Every other field (till,receipt_number,cashieras{ id, name }, and anything else) is passed on as sent. Makereceipt_numberunique 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) anderror.errors[](reason,message). A refusal, such as a short balance (there is no partial approval), is HTTP 200 withsuccess: 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-Versionheader as the other POS calls. Nothing is stored in Offers.
{ "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
checkis safe to repeat. The samecheck_idfrom 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.closeis idempotent onpos_transaction_idwithin 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 secondclosefor an already committed check with a different transaction id also reportscommitted: truewithout committing again.voidis idempotent onpos_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 newcheck_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 percheck) uses one. After that,checkanswers409 CHECK_REOPEN_LIMIT.
7. Timeouts and the fail-open rule
- Time
checkout at about 3 seconds. On timeout, a5xx, or a network error, close the check without a Spoonity discount. Do not block the cashier. - Always send
close, even after a failed or skippedcheck. It is cheap, idempotent, and it is how Spoonity finds out a check happened. - Retry
closeandvoidon5xxor network errors with backoff (for example 1 s, 5 s, 30 s, then store and forward). They are idempotent. - Do not retry
checkmore than once per attempt. - Do not retry a
4xx: it is a real answer. The one exception is409 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. - 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
closewhere it is turned on. When Spoonity has enabled the loyalty forward for the merchant, everyclosewith 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.closenever waits for it. The customer is the onecheckidentified, else thecustomer_code(orcustomer) sent onclose; a check with neither is recorded but not posted. Where it is not enabled for a merchant,closecommits 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.