# Spoonity Offers Spoonity Offers is Spoonity's promotions engine. A kiosk, POS, ordering app or partner sends it a cart. It decides which promotions and loyalty rewards apply, how they combine, and exactly how much comes off which line. Your system shows what it is given and submits it as it is. It never computes a discount itself. **Base URL:** `https://offers.spoonity.com` Two kinds of offer are priced together, in one pass: - **Merchant promotions**: promo codes, automatic deals, spend tiers, combos, happy hours. They cost no points and are usually open to guests. Merchants manage them in Spoonity Prism. - **Loyalty rewards**: point-cost rewards from the merchant's Spoonity loyalty program. Offers reads them from the loyalty platform. ## Rules that hold everywhere - **Integer cents.** Every amount is an integer number of cents (`1149` is $11.49). A decimal is a `400`. The one exception is `order_payload`, which is in decimal dollars because it goes to the loyalty platform's order endpoint. - **Pre-tax.** Every subtotal, discount and total is before tax. - **Deterministic.** The same request always gives the same answer. Ties are broken by fixed rules, not by chance or ordering. - **One discount per unit.** A line with `quantity: 3` is three units, and each unit carries at most one item discount. Item discounts apply first, then order discounts apply to what is left. - **Every offer explains itself.** Each offer in a response is `applied`, `applicable` (would apply if selected), `inapplicable` or `skipped`, with a stable `reason.code` and a `reason.message` you can show a guest or cashier. - **Fail open.** `503 OFFERS_UNAVAILABLE` means Offers could not price the cart right now. Take payment at full price; never block the sale. ## Surfaces | Surface | Paths | Who calls it | Credential | |---|---|---|---| | Evaluate and lifecycle | `/v1/evaluate`, `/v1/offers`, `/v1/redemptions/*`, `/v1/locks/*` | A kiosk, ordering app or channel backend that builds the cart itself | API key in `X-API-Key` or `Authorization: Bearer` | | POS check | `/partners/pos/*` | A POS that sends the whole check at pay time | POS key (`Authorization: Bearer`) | | App reward picks | `/partners/app/*` | A merchant's mobile app, so the customer can pick a reward before the till | The customer's loyalty session key (`Authorization: Bearer`) plus `X-Spoonity-Vendor` | | Admin catalog | `/v1/admin/*` | A merchant back office, or Prism | API key | | Health | `/readyz` | Monitoring | None | ## Which guide to read - **You build the cart yourself** (kiosk, web or app ordering, a channel backend): read the [kiosk and ordering app guide](kiosk.md). - **Your POS sends the whole check when the cashier presses pay**: read the [POS check guide](pos.md). - **You build a merchant's mobile app and want the customer to pick a reward before the till**: read the [app reward picks guide](app.md). - **You need every field, route and error code**: read the [API reference](reference.md). ## Getting a key Spoonity issues keys, one per merchant. There is no self-service sign-up. Ask your Spoonity account team for a key and for a test merchant to build against. Send keys only in headers: a key in a URL query string is refused, because URLs are written to request logs. ## Requests and errors - Send `Content-Type: application/json` on every request with a body. - Every response carries `X-Request-Id`. Send your own `X-Request-Id` to have it echoed and logged, and quote it when you report a problem. - Every error has the same shape: ```json { "error": { "code": "INVALID_REQUEST", "message": "Request validation failed", "issues": [] } } ``` `code` is stable and safe to branch on. `message` is for people. ## For AI coding assistants These docs are also published as plain markdown, so a coding assistant can read them directly: - [`/llms.txt`](/llms.txt): an index of every page with a one-line summary. - [`/docs/llms-full.txt`](/docs/llms-full.txt): every page in one file. - `/docs/.md`: any single page as markdown, for example [`/docs/pos.md`](/docs/pos.md) or [`/docs/reference.md`](/docs/reference.md). Give your assistant the page for your surface, and the reference, before it writes integration code. The rules above (integer cents, never compute a discount locally, fail open on `503`) are the ones most often gotten wrong. # Kiosk and ordering app guide For developers connecting a kiosk, ordering app or channel backend to Spoonity Offers. It assumes your device already builds a cart and takes payment. This page covers only the offers and rewards part of the flow: identifying the guest, showing offers, pricing the cart as it changes, and submitting the final order. Field-by-field detail for every route is in the [API reference](reference.md). If your POS sends the whole check at pay time instead of building a cart itself, read the [POS check guide](pos.md). **Money.** Every amount in requests and responses is **integer cents** (`550` is $5.50), except the fields inside `order_payload`, which are **decimal dollars** because they go straight to the Spoonity loyalty platform's `POST /order`. **Authentication.** Send your API key in a header on every `/v1/*` call: `X-API-Key: `, or `Authorization: Bearer `. The examples below use `X-API-Key: kiosk-demo-key`. A key sent as `?api_key=` in the URL is refused with `401 UNAUTHORIZED`, because URLs are written to request logs. ## The six steps ### 1. Identify the customer Identify the guest however your device already does it: card swipe, phone number, loyalty barcode or QR scan, or an onscreen check-in session. You do not call anything new for this. Pass the identifier to steps 2 and 4 as `customer.identifier`, or as `customer.pos_session_hash` if you already have a check-in session. If the guest does not identify, skip this step and see [Guests](#guests). ### 2. `GET /v1/offers` for the rewards screen Call this once you know who the guest is, or with no `customer` parameter for an anonymous teaser screen. It lists the offers currently visible to the guest. It does not run the engine: there is no cart, no totals and no eligibility check against a cart. ``` GET /v1/offers?customer=cust_demo_1 X-API-Key: kiosk-demo-key ``` ```json { "offers": [ { "offer_id": "birthday_free_drink", "name": "Birthday Free Drink", "pos_reference": "discount_birthday", "effect_type": "percent_off", "requires_code": false }, { "offer_id": "loyalty10", "name": "Loyalty Member 10% Off", "pos_reference": "discount_loyalty10", "effect_type": "percent_off", "requires_code": false } ] } ``` Offers that need a promo code never appear here, and the response never reveals a code. Point-cost rewards carry `cost_points`. Whether the guest can afford one is not checked until evaluate, so treat this list as "possibly available", not "will apply". ### 3. Build the cart Each line needs a `line_id` you own (unique within the cart), your SKU or PLU as `id`, the unit `price` in cents, and `quantity`. If you price modifiers separately, send the base price and list the modifiers; if you roll them into the item price, send the full price and no modifiers. Send the same `line_id` for the same item on every later evaluate. ```json { "line_items": [ { "line_id": "1", "id": "latte", "name": "Latte", "price": 550, "quantity": 1 }, { "line_id": "2", "id": "croissant", "name": "Croissant", "price": 325, "quantity": 1 } ] } ``` Lines may also carry `categories`, `modifiers` (each with its own unit `price` and `quantity`) and `discounts` your POS already applied. See the [API reference](reference.md#post-v1evaluate). ### 4. `POST /v1/evaluate` on every cart change Call it after every add, remove or quantity change, and whenever the guest picks or drops a reward. - **`evaluation_id`.** Pick one value per checkout attempt and reuse it on every evaluate for that attempt. It becomes the order's `receipt_number` in step 6. Do not create a new one per cart edit. It is 1 to 128 characters from `A-Z a-z 0-9 _ . : -`. - **`add_item_hint`.** A free-item offer whose item is not in the cart yet comes back `status: "applicable"` with `add_item_hint: { sku }` instead of a discount. Show it as a prompt ("Add a cookie to use this reward"). First call, nothing selected yet: ```json POST /v1/evaluate X-API-Key: kiosk-demo-key { "evaluation_id": "kiosk-1738000000000", "customer": { "identifier": "cust_demo_1" }, "cart": { "line_items": [ { "line_id": "1", "id": "latte", "price": 550, "quantity": 1 }, { "line_id": "2", "id": "croissant", "price": 325, "quantity": 1 } ] } } ``` ```json { "evaluation_id": "kiosk-1738000000000", "offers": [ { "offer_id": "birthday_free_drink", "name": "Birthday Free Drink", "status": "applicable", "source": { "type": "redemption", "vendor_perk_redemption_id": 101 }, "pos_reference": "discount_birthday", "discount_total": 550 }, { "offer_id": "loyalty10", "name": "Loyalty Member 10% Off", "status": "applied", "source": { "type": "redemption", "vendor_perk_redemption_id": 102 }, "pos_reference": "discount_loyalty10", "discount_total": 88 }, { "offer_id": "min_spend_15", "name": "Spend $15, Save 15%", "status": "inapplicable", "source": { "type": "redemption", "vendor_perk_redemption_id": 103 }, "pos_reference": "discount_min15", "reason": { "code": "MIN_SPEND_NOT_MET", "message": "Spend $15.00 to unlock", "shortfall": 625 } } ], "cart": { "subtotal": 875, "discount_total": 88, "total": 787, "line_items": [], "discounts": [], "allocations": [] }, "effects": [], "receipt_lines": ["Loyalty Member 10% Off applied, you saved $0.88"], "lock": null, "redemption_id": null, "accrual_preview": null, "order_payload": {} } ``` Arrays and objects in this example are shortened. `loyalty10` applied on its own because the offer is `auto_apply`. `birthday_free_drink` is only `applicable` because nobody selected it: in the default `manual` selection mode an offer applies only when it is selected, unlocked with a code, or `auto_apply`. Show every `applicable` and `inapplicable` offer with its `reason.message` so the guest knows what they can unlock and why something is not available. `receipt_lines` are ready-to-print text. Treat them as display text, not a contract: the wording may change (today the two halves are separated by a dash rather than the comma shown here). `accrual_preview` is an estimate of points earned when the merchant's loyalty data supports it, and `null` otherwise. It is never authoritative; the loyalty platform computes real points when the order is posted. When the guest picks an offer, evaluate again with it in `selected`: ```json POST /v1/evaluate X-API-Key: kiosk-demo-key { "evaluation_id": "kiosk-1738000000000", "customer": { "identifier": "cust_demo_1" }, "cart": { "line_items": [] }, "selected": ["birthday_free_drink"] } ``` (`line_items` shortened; send the full cart.) Each evaluate with the same `evaluation_id` replaces the previous result. Always send the full current cart and the full current selection. ### 5. Final evaluate with `lock` before payment Just before payment, evaluate once more with a `lock`. This reserves single-use offers, so a second order running at the same time cannot redeem the same "one per guest" reward, and records a pending redemption. ```json POST /v1/evaluate X-API-Key: kiosk-demo-key { "evaluation_id": "kiosk-1738000000000", "customer": { "identifier": "cust_demo_1" }, "cart": { "line_items": [] }, "selected": ["birthday_free_drink"], "lock": { "ttl_seconds": 300 } } ``` ```json { "evaluation_id": "kiosk-1738000000000", "offers": [ { "offer_id": "birthday_free_drink", "name": "Birthday Free Drink", "status": "applied", "source": { "type": "redemption", "vendor_perk_redemption_id": 101 }, "pos_reference": "discount_birthday", "discount_total": 550 }, { "offer_id": "loyalty10", "name": "Loyalty Member 10% Off", "status": "applied", "source": { "type": "redemption", "vendor_perk_redemption_id": 102 }, "pos_reference": "discount_loyalty10", "discount_total": 33 }, { "offer_id": "min_spend_15", "name": "Spend $15, Save 15%", "status": "inapplicable", "source": { "type": "redemption", "vendor_perk_redemption_id": 103 }, "pos_reference": "discount_min15", "reason": { "code": "MIN_SPEND_NOT_MET", "message": "Spend $15.00 to unlock", "shortfall": 625 } } ], "cart": { "subtotal": 875, "discount_total": 583, "total": 292, "line_items": [], "discounts": [], "allocations": [ { "line_id": "2", "offer_id": "loyalty10", "amount": 33 } ] }, "effects": [], "receipt_lines": [ "Birthday Free Drink applied, you saved $5.50", "Loyalty Member 10% Off applied, you saved $0.33" ], "lock": { "key": "lock_3f2a", "expires_at": "2026-08-04T12:35:00.000Z" }, "redemption_id": "ored_9c1b", "accrual_preview": null, "order_payload": { "receipt_number": "kiosk-1738000000000", "subtotal": 8.75, "total": 2.92, "line_items": [ { "id": "latte", "name": "Latte", "price": 5.50, "quantity": 1, "discounts": [{ "id": "discount_birthday", "name": "Birthday Free Drink", "amount": 5.50 }] }, { "id": "croissant", "name": "Croissant", "price": 3.25, "quantity": 1, "discounts": [] } ], "discounts": [{ "id": "discount_loyalty10", "name": "Loyalty Member 10% Off", "amount": 0.33 }] } } ``` `loyalty10` still applies alongside the selected birthday reward because neither is exclusive. Item discounts are applied first, so the latte is free, and the order-level 10% then applies to what is left: 10% of the $3.25 croissant is $0.33. **Releasing a lock.** If the guest cancels after this point, either evaluate again (which replaces the lock) or release it with `DELETE /v1/locks/{key}` so the single-use offer is free at once instead of after the TTL. Releasing also cancels the pending redemption, and a cancelled redemption never commits. Use a new `evaluation_id` for the next attempt: evaluating again with the cancelled id answers `409 EVALUATION_TERMINAL`. **Lock expiry.** A lock and its pending redemption last `ttl_seconds` (1 to 3600). If no order follows, the redemption expires and any reserved single-use offers become available again; the service sweeps for expired holds every 60 seconds. If payment can take longer than the TTL, evaluate again with `lock` before it expires; that simply replaces the lock. If the lock has already expired, evaluate with a **new** `evaluation_id` and `lock` to get a fresh redemption. An expired redemption is terminal and its id answers `409 EVALUATION_TERMINAL`. A commit that arrives after `expires_at` is refused even if the sweep has not run yet. ### 6. Submit `order_payload` to Spoonity `POST /order` Send the `order_payload` from step 5 to the Spoonity loyalty platform's `POST /order`, unchanged. Do not recompute `subtotal`, `total` or `discounts`; they are already correct, in decimal dollars, and match the cents you were shown. Keep `receipt_number` equal to the `evaluation_id` you locked with. ```json POST /order (Spoonity loyalty platform, not this service) { "receipt_number": "kiosk-1738000000000", "subtotal": 8.75, "total": 2.92, "line_items": [], "discounts": [] } ``` (`line_items` and `discounts` are `order_payload`'s, sent as they are.) Points are earned from this order by the loyalty platform, as today. ### How the redemption commits Posting the order does not by itself commit the redemption in Offers. A pending redemption becomes `committed` when Offers receives an `order.submitted` event on `POST /webhooks/events` carrying the same `receipt_number`. That route is authenticated with a secret Spoonity holds; your device does not call it. **Check this before you go live.** The Spoonity loyalty platform does not send `order.submitted` to Offers automatically today. Spoonity sets up the event path per integration. Until it is in place for your merchant, a locked redemption is never committed: it expires when the lock lapses, single-use rewards can be used again, and usage limits and budgets do not count the order. Discounts are still priced correctly. Ask your Spoonity contact to confirm the commit path before you rely on single-use offers or usage limits. A POS that can send the whole check at pay time can use the [POS check guide](pos.md) instead. On that surface `close` commits directly and needs no event. **Single-use reasons.** Two reasons apply only to single-use offers and come back as `inapplicable`: `ALREADY_USED` (this customer already committed a redemption of it) and `RESERVED` (another order in progress holds it; it may free up if that order is abandoned). Both carry a `message` you can show the guest. Neither is an error. ## Guests A guest who does not identify can still check out. Leave `customer` out of `GET /v1/offers` and `POST /v1/evaluate`. Only offers that need no specific customer can apply: open promotions and promo codes sent in `codes`. Offers gated by tier or points come back `inapplicable` (`TIER_NOT_ELIGIBLE`, `INSUFFICIENT_BALANCE`) or are left out. There is no guest flag to set. ## Errors Every non-2xx response has the same shape: ```json { "error": { "code": "INVALID_REQUEST", "message": "Request validation failed", "issues": [] } } ``` | Code | Status | What to do | |---|---|---| | `UNAUTHORIZED` | 401 | Missing or wrong key, or a key sent as `?api_key=`. A configuration problem; do not retry. | | `INVALID_REQUEST` | 400 | Malformed cart, duplicate `line_id`, `quantity` or `price` out of range, `ttl_seconds` out of range, or an `evaluation_id` with characters outside the allowed set. `issues` says where. Fix and resend. | | `OFFERS_RESERVED` | 409 | Only on a `lock` request: another order in progress holds one of the single-use offers. `error.conflict_offer_ids` names them. Drop them from `selected` and evaluate again. | | `EVALUATION_TERMINAL` | 409 | This `evaluation_id` already has a committed, cancelled or expired redemption. Start again with a new id. | | `OFFERS_UNAVAILABLE` | 503 | Offers could not read what it needs. **Take payment without discounts.** Do not block the sale. | | `UNKNOWN_LINES` | 400 | On `/returns`: some `line_ids` are not part of that redemption. | | `INVALID_STATE` | 409 | On `/returns`: the redemption is not committed. | | `NOT_FOUND` | 404 | Management routes: unknown id, or a record that belongs to another merchant. | | `INTERNAL` | 500 | A bug on our side. Retry once, then drop the discount, not the sale. | Treat any code you do not recognise as a failure. Do not read partial success into a non-2xx body. `OFFERS_UNAVAILABLE` exists so that an outage costs the guest their discount, not their order. **Limits.** 200 lines per cart, 1 to 1000 units per line, 2000 units per cart, amounts up to 100,000,000 cents ($1,000,000), at most 50 entries in `codes`, `selected`, `categories` and `modifiers`, at most 10 `discounts` per line. A request over a limit is a `400`. ## Two behaviours worth knowing **Code-gated offers are absent, not `inapplicable`.** An offer that needs a promo code does not appear in `offers[]` at all until the matching code is in `codes`. `GET /v1/offers` leaves it out too, so the API never reveals a code. A wrong code therefore looks like an unchanged response, not a rejection; tell the guest yourself. **`receipt_number` must equal `evaluation_id`.** Nothing rejects a mismatch, but the commit event matches on it, so a mismatch means the redemption never commits. ## What you never do - **Discount math.** You never compute a percent off, a free unit or a per-line split. Every number in the response is final. - **Stacking.** You never decide which of two offers wins or whether they combine. Each offer's `status` and `reason` already reflect that. - **Tax on discounts.** Every total here is pre-tax. Apply tax as you already do, on `order_payload.total`. # 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 ` on every request (`X-Spoonity-POS-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=` | `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": }`. 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. # App reward picks (`/partners/app`) This guide is for developers of a merchant's mobile app. It lets a customer pick a loyalty reward in the app before they reach the till. When the cashier scans the customer's code, the POS check finds the pick and applies it. The POS never sees a list of rewards. **Base URL:** `https://offers.spoonity.com`, or the host the merchant's POS integration uses. Path prefix: `/partners/app`. ## 1. The flow 1. The customer opens the app and picks a reward: `POST /partners/app/selections`, with the code the app is showing. 2. The app shows the pick as ready at the till, and sends its new code to `PUT /partners/app/code` every time the code changes. 3. The cashier scans the customer's code. The POS sends it on its `check` call (see the [POS check guide](pos.md)). 4. Spoonity finds the customer's picks for today and applies them to the check. The pick is held while the check is open and used when it closes. The app takes no part in steps 3 and 4. It can list the picks again to show that one is at the till. ## 2. Authentication Every request sends two headers: ``` Authorization: Bearer X-Spoonity-Vendor: ``` - `session_key` is the customer's Spoonity loyalty session, the same one the app already uses for the native API. It is never an API key. Do not put an API key in an app. - `X-Spoonity-Vendor` is the merchant's Spoonity vendor id. - Spoonity validates the session on the merchant's loyalty host and keeps a valid session for 5 minutes. A sign-out is therefore seen within 5 minutes. - The session decides who the customer is. The body never names a customer or a vendor. - `Content-Type: application/json` on requests with a body. Unknown fields are a `400`. ## 3. POST /partners/app/selections Pick a reward for today. Send exactly one of `reward_id` or `offer_id`: ```json { "reward_id": 501 } ``` ```json { "offer_id": "off_r501" } ``` `reward_id` is the loyalty reward id the app already lists (`vendor_perk_redemption_id`). It maps to the offer `off_r`. Send the code the app is showing with the pick, so the till recognises the customer: ```json { "reward_id": 501, "code": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "customer_identifier": "ada@example.com" } ``` | Field | Type | Meaning | |---|---|---| | `code` | string, 1 to 512, optional | The scannable code the app is showing right now, exactly as the cashier will scan it. When the merchant's POS recognises codes by a prefix, it may be sent with or without it: Spoonity stores it without the prefix, as the till looks it up. | | `customer_identifier` | string, 1 to 256, optional | The merchant's default customer identifier (for example the loyalty token, email or phone). Spoonity names the customer by it when it posts the sale to the loyalty program. Used together with `code`. | Response `201` for a new pick, or `200` when this reward was already picked today (the same pick is returned): ```json { "selection": { "selection_id": "sel_8d0c6f5e-4b7a-4a51-9a59-0d1f8f0c1e2a", "offer_id": "off_r501", "reward_id": 501, "name": "Free Fries", "business_date": "2026-10-15", "expires_at": "2026-10-16T08:00:00.000Z", "state": "open" } } ``` Spoonity checks once, at pick time, that this customer can have the reward now: points, tier, segment, active dates, and whether it was already used. It does not check the cart (minimum spend, items), the store or the time of day. Those are judged at the till. How many picks apply on one check is decided at the till by the merchant's promotion policy, not here. ## 4. GET /partners/app/selections Today's picks that can still apply, oldest first. ```json { "selections": [ { "selection_id": "sel_8d0c6f5e-4b7a-4a51-9a59-0d1f8f0c1e2a", "offer_id": "off_r501", "reward_id": 501, "name": "Free Fries", "business_date": "2026-10-15", "expires_at": "2026-10-16T08:00:00.000Z", "state": "pending" } ] } ``` | `state` | Meaning | |---|---| | `open` | Picked, waiting for the till. | | `pending` | A POS check has applied it and holds it until the check closes (at most 15 minutes). Show it as "at the till". | Used, cancelled and expired picks are not listed. ## 5. DELETE /partners/app/selections/:selection_id Take a pick back. Response `200`: ```json { "cancelled": true } ``` - Repeating it gives the same answer. - A `pending` pick can be cancelled. The check already at the till keeps its discount on screen; the pick is just not applied to the next check. - A pick that belongs to another customer or another merchant answers `404`. - A pick whose check has closed answers `409 SELECTION_USED`. ## 6. PUT /partners/app/code Tell Spoonity the code the app is showing now. Call it every time the code changes while the customer has an open pick today (loyalty codes rotate every few minutes). ```json { "code": "ffeeddccbbaa99887766554433221100", "customer_identifier": "ada@example.com" } ``` Response `204` with no body. The fields are those of `POST /partners/app/selections`; `code` is required. - A code is valid until the end of the merchant's business day. - Spoonity keeps the 20 most recent codes per customer per business day. - A code sent again by another customer now belongs to that customer. - Spoonity stores only a hash of the code. ## 7. Business day A pick is valid until the end of the merchant's business day. The day starts at a local cutoff in the merchant's time zone, so a pick made at 01:30 on Saturday, with a 04:00 cutoff, belongs to Friday's business day and expires at 04:00 on Saturday. - `expires_at` is the end of the business day in UTC. Use it to show and to hide a stale pick. - `business_date` is the local date the business day is named after. - Do not work out the business day on the device. Around daylight saving changes a business day is 23 or 25 hours long. ## 8. How a pick reaches the POS check 1. The POS sends the scanned code as `customer.customer_id` on `POST /partners/pos/check`. 2. Spoonity resolves the code to the customer and loads that customer's `open` and `pending` picks for today at that merchant. 3. The picks join the check's selected offers. A pick that applies becomes `pending`, linked to that check. 4. When the check closes, the pick is `used`. If the check is voided while open, its hold lapses, or a later `check` for it no longer applies the pick, the pick goes back to `open`. ``` pick check applies it close (none) ------> open ---------------------------> pending ---------> used ^ \ | | \ DELETE | void while open, hold expired, | v | or re-check without it | cancelled | +------------------------------------+ open or pending past expires_at: expired (not listed, not applied) ``` A pick never applies to another merchant's check. When the merchant is set up for app picks, Spoonity recognises the customer from the codes the app sent, without asking the loyalty platform at the till. A code the app never sent prices the check as a guest, so send the code with every pick and every time it changes. ## 9. Errors Error bodies are `{ "error": { "code": "...", "message": "..." } }`. | Status | `code` | When | App action | |---|---|---|---| | 400 | `INVALID_REQUEST` | The body failed validation (`issues[]` says where), for example both `reward_id` and `offer_id`, or neither. | Fix the request. | | 401 | `UNAUTHORIZED` | A header is missing, the session is invalid or expired, the merchant is not set up for picks, or the session has no loyalty account at this merchant. | Sign the customer in again. | | 404 | `NOT_FOUND` | No such pick for this customer. | Refresh the list. | | 409 | `OFFER_NOT_AVAILABLE` | The customer cannot have the reward now. `error.reason.code` says why and `error.reason.message` can be shown. | Show the message. | | 409 | `TOO_MANY_SELECTIONS` | The customer already has 10 open picks today. | Ask them to cancel one first. | | 409 | `SELECTION_USED` | The check that applied the pick has closed. | Refresh the list. | | 413 | `PAYLOAD_TOO_LARGE` | The body is over 256 KB. | Fix the request. | | 429 | `RATE_LIMITED` | Too many requests. The `Retry-After` header gives the seconds to wait. | Wait, then retry. | | 500 | `INTERNAL` | An error on Spoonity's side. | Retry later. | | 503 | `LOYALTY_UNAVAILABLE` | The merchant's loyalty host could not be reached. | Retry later. | | 503 | `UNAVAILABLE` | Spoonity's database is temporarily unavailable. | Retry later. | `error.reason.code` on `OFFER_NOT_AVAILABLE` is one of `OFFER_NOT_FOUND`, `INSUFFICIENT_BALANCE`, `TIER_NOT_ELIGIBLE`, `CONDITION_NOT_MET`, `ALREADY_USED`, `RESERVED`, `USAGE_LIMIT_REACHED`, `OUTSIDE_ACTIVE_WINDOW`, `CHANNEL_NOT_ELIGIBLE`, `CODE_REQUIRED` and `BUDGET_EXHAUSTED`. See the [reason codes](reference.md#reason-codes) in the reference. ## 10. Limits - 10 open picks per customer per business day. Two picks sent at the same moment can both succeed, so the count can reach 11 in that race. - Requests are rate limited per credential. See the [rate limit](reference.md#rate-limits) section of the reference. # Spoonity Offers API Spoonity Offers is the promotions engine. A kiosk, POS, ordering app or partner sends it a cart; it decides which promotions and loyalty rewards apply, how they combine, and exactly how much comes off which line. The caller displays what it is given and submits it as-is. It never computes a discount itself. Two kinds of offer are evaluated together, in one pass: - **Merchant promotions**: promo codes, automatic deals, spend tiers, combos, happy hours. They cost no points and are usually open to guests. They live in the engine's own catalog and are managed with the [admin catalog API](#admin-catalog-api) below (Prism's Promotions section uses the same API). - **Loyalty rewards**: point-cost rewards defined in the Spoonity loyalty program. The engine reads them from the loyalty platform; they are read-only here. **Base URL:** `https://offers.spoonity.com` Machine-readable spec: [openapi/offers.yaml](https://prism.spoonity.com/docs/openapi/offers.yaml) (OpenAPI 3.1). ## How the engine decides The same input always produces the same output. These rules hold on every surface on this page. - **Integer cents.** Every amount in a request and a response is an integer number of cents (`1149` is $11.49). A decimal is a `400`. The one exception is `order_payload` in the evaluate response, which is in decimal dollars because it is built for the loyalty platform's order endpoint. - **Pre-tax.** Every subtotal, discount and total is before tax. Tax is applied downstream by the POS or loyalty platform. - **Deterministic.** The engine takes the clock as an input and never reads it mid-evaluation. Ties are broken by explicit rules (price, then cart position, then offer id), not by iteration order. - **One discount per unit.** A cart line with `quantity: 3` is three units. Each unit can carry at most one item-level discount. Item-level offers are applied first; order-level offers then apply to what is left. - **Allocation that adds up.** An order-level discount is spread across the lines with a largest-remainder method, so the per-line `allocations` always sum to the discount. - **Stacking.** Arbitration order is: offers the guest selected or unlocked with a code, then higher `stacking.priority`, then the higher standalone value for this cart, then offer id. Three controls limit combination: - `stacking.exclusive: true`: once an exclusive offer applies, every other requested offer is skipped with `EXCLUSIVE_CONFLICT`. - `stacking.group`: one applied offer per group; the rest are skipped with `GROUP_CONFLICT`. - The vendor's [promotion policy](#the-promotion-policy): a cap on applied offers (`MAX_OFFERS_REACHED`), a cap on the order discount as a percent (`ORDER_CAP_REACHED`), and whether order-level percentages cascade or add. - **Reason codes.** Every offer in a response has exactly one status: `applied`, `applicable` (would apply if selected), `inapplicable` (failed an eligibility check) or `skipped` (lost arbitration). An offer that did not apply carries `reason: { code, message, ... }`. `code` is stable and machine-readable; `message` is display text for a guest or cashier. See [Reason codes](#reason-codes). - **Discounts the POS already applied.** A line may carry `discounts` the register applied itself (employee, manager, senior). Order-level discounts are always computed on the total after them, and by default the engine does not add an item-level discount to such a line (`LOCALLY_DISCOUNTED`). ## Surfaces | Surface | Paths | Who calls it | Credential | |---|---|---|---| | Evaluate and lifecycle | `/v1/evaluate`, `/v1/offers`, `/v1/redemptions/*`, `/v1/locks/*` | A kiosk, ordering app or channel backend that builds the cart itself | Vendor API key | | Admin catalog | `/v1/admin/*` | A merchant's back office, or Prism | Vendor API key, or OIDC service identity | | POS check | `/partners/pos/*` | A POS that sends the whole check at pay time | POS key (`Authorization: Bearer`) | | App reward picks | `/partners/app/*` | A merchant's mobile app, so a customer can pick a reward before the till | Customer session key (`Authorization: Bearer`) plus `X-Spoonity-Vendor` | | Health | `/readyz` | Monitoring | None | ## Authentication Offers accepts four credentials. Which one applies depends on the path. [Authentication](https://prism.spoonity.com/docs/authentication#offers) covers them alongside the other services. ### Vendor API key (`/v1/*`) Send the key in either header: ``` X-API-Key: YOUR_OFFERS_API_KEY ``` ``` Authorization: Bearer YOUR_OFFERS_API_KEY ``` `X-API-Key` is checked first. The key determines the vendor; no request carries a vendor id. Keys are issued by Spoonity. There is no self-service key page for Offers in Prism. The key must be in a header. On `offers.spoonity.com` a request with `?api_key=` in the URL is refused with `401 UNAUTHORIZED` even when the key is correct, because URLs are written to request logs. An API key has no role, so it can call every `/v1/*` route, including admin writes. ### POS key (`/partners/pos/*`) ``` Authorization: Bearer YOUR_POS_KEY ``` `X-Spoonity-POS-Key: YOUR_POS_KEY` is also accepted. The key alone determines the merchant and the store; no vendor or store id is ever read from the body or query (there is no `store_id` field). Two kinds of key work: - A key Spoonity issued for the merchant. The merchant is also the store. - A store's own Spoonity API key (a store vendor under the merchant). The first request with a key Spoonity has not seen is checked once with the loyalty program; when the key belongs to a store of a merchant connected to Offers, it is remembered and accepted from then on. The request runs for the merchant (promotions, app picks, codes and settings are the merchant's), the store is the key's store, and the store's closed checks are posted to the loyalty program with the store's own key. A missing or unknown key, a store key of another merchant, and a key the loyalty program no longer accepts (deactivated, expired or deleted) are `401 UNAUTHORIZED`. A key the loyalty program rejects on any call is revoked and stays refused: replace it in the POS configuration. When a new key cannot be checked because the loyalty program is down, the answer is `503 OFFERS_UNAVAILABLE` and nothing is remembered. The `/v1` credentials are not accepted on `/partners/pos`, and a POS key is not accepted on `/v1`. ### Customer session (`/partners/app/*`) ``` Authorization: Bearer CUSTOMER_SESSION_KEY X-Spoonity-Vendor: 2112901 ``` The customer's Spoonity loyalty session, never an API key. The session is validated on the merchant's loyalty host and a valid session is cached for 5 minutes. The session decides the customer; the body never does. A missing header, an invalid session or an unknown vendor is `401 UNAUTHORIZED`. [App reward picks](#app-reward-picks-api) has the endpoints. ### OIDC service identity (trusted Spoonity services) Trusted Spoonity services such as Prism's BFF call `/v1/*` with a Google-signed ID token instead of a key. This path is not available to external integrators; it is listed so the headers you see Prism send make sense. | Header | Required | Meaning | |---|---|---| | `Authorization: Bearer ` | Yes | Token for an allow-listed service account, with this service as the audience | | `X-Spoonity-Vendor` | Yes, `^[A-Za-z0-9_-]{1,64}$` | The vendor the call acts for. Missing or malformed is `401` | | `X-Spoonity-User` | No, 1 to 256 printable characters | The person acting; stamped on `created_by` / `updated_by` | | `X-Spoonity-Role` | No | Exactly `admin`, `editor` or `viewer`. Absent, or any other value, is treated as `viewer` | A `viewer` gets `403 FORBIDDEN` on every non-GET `/v1/admin/*` route except `POST /v1/admin/promotions/simulate`, which has no side effects. ## Conventions - **Errors** use one envelope everywhere on this service: ```json { "error": { "code": "INVALID_REQUEST", "message": "Promotion validation failed", "issues": [ { "path": "discount_amount", "message": "percent discounts must be between 0 and 100" } ] } } ``` `code` is the stable part. `issues[]` appears on validation errors, one entry per field. Some codes add fields (`version`, `conflict_offer_ids`, `state`); each endpoint lists them. This differs from CMS and Links, whose `error` is a string; see [Conventions](https://prism.spoonity.com/docs/conventions#error-envelope). - **Unknown fields.** Admin and POS request bodies reject unknown fields with `400`, so a typo cannot silently change a promotion. On `/partners/pos`, fields of your own go in `metadata`, which is accepted and ignored. `POST /v1/evaluate` ignores fields it does not know. - **Limits.** 200 lines per cart, 1 to 1000 units per line, 2000 units per cart, amounts 0 to 100,000,000 cents, at most 50 entries in `codes`, `selected`, `categories` and `modifiers`. Over any limit is a `400`. - **Identifiers.** `evaluation_id`, promotion `identifier`, `requires_code` and `stacking.group` are 1 to 128 characters from `A-Z a-z 0-9 _ . : -`. SKUs, category ids and other ids you own are 1 to 128 characters of anything. - **Timestamps.** Promotion, policy and redemption records use epoch milliseconds (`created_at`, `updated_at`, `committed_at`). Lock and hold expiries are ISO 8601 strings. Usage days are `YYYY-MM-DD` UTC dates. - **Versioning.** The version is in the path (`/v1`). The POS check API (`/partners/pos`) answers with `X-Spoonity-Api-Version: 2026-10-16`; see [POS check API](#pos-check-api). - **Request ids.** Every response carries `X-Request-Id`. Send your own `X-Request-Id` to have it echoed and logged; quote it when reporting a problem. - **Fail open.** A `503 OFFERS_UNAVAILABLE` means the engine could not read what it needs (catalog, policy, database). It is retryable. A checkout that receives it should proceed at full price rather than block the guest. ## Evaluate and lifecycle A device that builds its own cart uses this surface. The loop: 1. **Evaluate on every change.** Call `POST /v1/evaluate` whenever the cart or the guest's selection changes. Reuse one `evaluation_id` for the whole checkout attempt; each call replaces the previous result for that id. Always send the full current cart and selection. 2. **Lock before payment.** Call it once more with `lock: { ttl_seconds }`. This reserves single-use offers so a concurrent order cannot take them, and records a `pending` redemption. The response carries `redemption_id` and `lock`. 3. **Submit the order.** Send `order_payload` to the loyalty platform unchanged. Its `receipt_number` is the `evaluation_id`. 4. **Commit is event-driven.** When the order lands, an `order.submitted` event posted to [`/webhooks/events`](#post-webhooksevents) turns the pending redemption into `committed`. A device never calls a commit endpoint. A pending redemption that is never committed expires when its hold lapses, and an expired one does not count against single-use offers or usage limits. 5. **Undo when needed.** Release an abandoned lock with `DELETE /v1/locks/{key}`, or roll back, cancel or partially return a redemption with the `/v1/redemptions/{id}` routes. Redemption states: ``` pending --commit--> committed --return--> partially_returned | | | | +--------rollback--------+--> rolled_back +--cancel / void--> cancelled +--hold lapses----> expired ``` `rolled_back`, `cancelled` and `expired` are terminal. A commit that arrives after the hold expired is refused and the record expires, so a lapsed hold can never commit. Usage limits and budgets are computed from committed records, so a rollback restores both the use and the budget. A partial return restores neither. ### POST /v1/evaluate Price a cart against the vendor's promotions and loyalty rewards. **Auth:** Vendor API key, or OIDC service identity. #### Request body | Field | Type | Required | Description | |---|---|---|---| | `evaluation_id` | string | Yes | Your id for this checkout attempt. Reuse it on every call for the attempt. Becomes `order_payload.receipt_number` | | `cart.line_items[]` | array | Yes | 1 to 200 lines, see below | | `customer.identifier` | string | | Loyalty customer identifier. Resolves tier, segments, balances and pre-selected rewards when the vendor's loyalty program is connected to Offers; otherwise the cart is priced for a guest | | `customer.pos_session_hash` | string | | Alternative identifier from a POS session | | `customer.order_count` | integer | | Orders the customer has placed, if you know it. A value the loyalty platform resolves wins | | `customer.tags` | string[] | | Customer tags, if you know them. A resolved list wins | | `codes` | string[] | | Promo codes the guest entered | | `selected` | string[] | | Offer ids the guest chose (typically point-cost rewards) | | `selection_mode` | string | | `manual` (default): only selected, code-unlocked and auto-apply offers apply. `automatic`: every eligible offer is treated as requested. `list`: nothing applies; eligible offers come back `applicable`, for a picker UI | | `store_id` | string | | Store, for store-restricted offers | | `channel` | string | | Channel, for example `kiosk`, `web`, `pos` | | `lock.ttl_seconds` | integer | | 1 to 3600. Marks this as the final evaluate before payment: reserves single-use offers and records a pending redemption | A line is `{ line_id, id, name?, categories?, price, quantity, modifiers?, discounts? }`: | Field | Type | Description | |---|---|---| | `line_id` | string | Unique within the cart | | `id` | string | Your SKU or PLU. Promotions target it through `products` | | `categories[]` | `{ id, name? }` | Promotions target these through `categories` | | `price` | integer cents | Unit price excluding modifiers | | `quantity` | integer | 1 to 1000 | | `modifiers[]` | `{ id, name?, price, quantity }` | Unit price and quantity per modifier | | `discounts[]` | `{ id, name?, amount, source? }` | Discounts the POS already applied to the whole line, cents. At most 10. `source` is `pos` (default) or `external` | #### Example request ```bash curl -X POST https://offers.spoonity.com/v1/evaluate \ -H "X-API-Key: YOUR_OFFERS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "evaluation_id": "K12-000482", "channel": "kiosk", "store_id": "store_12", "customer": { "identifier": "cust_1001" }, "codes": ["WELCOME3"], "selected": ["reward_free_cookie"], "cart": { "line_items": [ { "line_id": "1", "id": "cola", "name": "Cola", "categories": [{ "id": "drinks" }], "price": 279, "quantity": 2 }, { "line_id": "2", "id": "cookie", "name": "Cookie", "categories": [{ "id": "desserts" }], "price": 199, "quantity": 1 } ] } }' ``` #### Example response `200`. The free cookie (a 150-point loyalty reward the guest selected) and a $3 code both applied. "20% off drinks" and the combo are `applicable`: they would apply if requested (the combo still needs a main and a side). The spend tier is not reached. ```json { "evaluation_id": "K12-000482", "offers": [ { "offer_id": "reward_free_cookie", "name": "Free Cookie (150 pts)", "status": "applied", "source": { "type": "redemption", "vendor_perk_redemption_id": 501 }, "pos_reference": "discount_free_cookie", "cost_points": 150, "discount_total": 199 }, { "offer_id": "promo_WELCOME3", "name": "$3 Off with Code WELCOME3", "status": "applied", "source": { "type": "promotion_code", "code": "WELCOME3" }, "pos_reference": "discount_promo_WELCOME3", "funding": "restaurant", "discount_total": 300 }, { "offer_id": "promo_DRINKS20", "name": "20% off drinks", "status": "applicable", "source": { "type": "promotion_code" }, "pos_reference": "discount_promo_DRINKS20", "discount_total": 112 }, { "offer_id": "promo_SPEND20", "name": "Spend more, save more", "status": "inapplicable", "source": { "type": "promotion_code" }, "pos_reference": "discount_promo_SPEND20", "reason": { "code": "TIER_NOT_REACHED", "message": "Spend $20.00 to unlock", "next_min_spend": 2000, "shortfall": 1243 } }, { "offer_id": "promo_LUNCHCOMBO", "name": "Lunch combo $10.99", "status": "applicable", "source": { "type": "promotion_code" }, "pos_reference": "discount_promo_LUNCHCOMBO", "reason": { "code": "BUNDLE_INCOMPLETE", "message": "Add the remaining items to complete this combo", "missing": [ { "component": 0, "required": 1, "available": 0 }, { "component": 1, "required": 1, "available": 0 } ] } } ], "cart": { "line_items": [ { "line_id": "1", "id": "cola", "name": "Cola", "categories": [{ "id": "drinks" }], "price": 279, "quantity": 2, "discounts": [] }, { "line_id": "2", "id": "cookie", "name": "Cookie", "categories": [{ "id": "desserts" }], "price": 199, "quantity": 1, "discounts": [ { "id": "discount_free_cookie", "name": "Free Cookie (150 pts)", "amount": 199, "offer_id": "reward_free_cookie", "unit_index": 0, "quantity": 1 } ] } ], "discounts": [ { "id": "discount_promo_WELCOME3", "name": "$3 Off with Code WELCOME3", "amount": 300, "offer_id": "promo_WELCOME3" } ], "allocations": [ { "line_id": "1", "offer_id": "promo_WELCOME3", "amount": 300 } ], "subtotal": 757, "discount_total": 499, "total": 258 }, "effects": [ { "type": "order_discount", "offer_id": "promo_WELCOME3", "amount": 300, "pos_reference": "discount_promo_WELCOME3", "allocations": [{ "line_id": "1", "offer_id": "promo_WELCOME3", "amount": 300 }], "funding": "restaurant" }, { "type": "item_discount", "offer_id": "reward_free_cookie", "line_id": "2", "unit_index": 0, "quantity": 1, "amount": 199, "pos_reference": "discount_free_cookie" } ], "receipt_lines": [ "Free Cookie (150 pts) applied \u2014 you saved $1.99", "$3 Off with Code WELCOME3 applied \u2014 you saved $3.00" ], "lock": null, "redemption_id": null, "accrual_preview": null, "order_payload": { "receipt_number": "K12-000482", "subtotal": 7.57, "total": 2.58, "line_items": [ { "id": "cola", "name": "Cola", "categories": [{ "id": "drinks" }], "price": 2.79, "quantity": 2, "discounts": [] }, { "id": "cookie", "name": "Cookie", "categories": [{ "id": "desserts" }], "price": 1.99, "quantity": 1, "discounts": [{ "id": "discount_free_cookie", "name": "Free Cookie (150 pts)", "amount": 1.99 }] } ], "discounts": [ { "id": "discount_promo_WELCOME3", "name": "$3 Off with Code WELCOME3", "amount": 3 } ] } } ``` The same request with `"lock": { "ttl_seconds": 300 }` returns the same body with these three fields filled in: ```json { "evaluation_id": "K12-000482", "lock": { "key": "lock_73effdbf-a2b9-463c-b462-0a2a03032669", "expires_at": "2026-09-30T10:35:19.390Z" }, "redemption_id": "ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0" } ``` Reading the response: - `offers[]`: every candidate offer with its status. Code-gated offers whose code was not entered are left out entirely. - `cart`: the repriced cart. Item discounts are on `line_items[].discounts` (`id` is the `pos_reference`), order discounts on `cart.discounts`, and `allocations` spreads each order discount across lines for refunds. `total` is `subtotal` minus `external_discount_total` (present only when lines carried POS discounts) minus `discount_total`. - `effects[]`: the same result as instructions for a POS: `item_discount` (line, first unit, unit count, amount), `order_discount` (amount plus allocations) and `add_item_hint` (a free item offer whose SKU is not in the cart; also shown as `add_item_hint: { sku }` on the offer). `funding` is `restaurant`, `channel`, `shared` or `loyalty`; absent means `restaurant`. It is attribution only and never changes the amounts. - `receipt_lines`: printable lines. Treat them as display text; the wording can change. The engine separates the two halves with a dash character, shown escaped above. - `lock` and `redemption_id`: `null` unless `lock` was requested and the result has something to record. - `accrual_preview`: an estimate of points earned, when the loyalty source provides an earn rate; otherwise `null`. The loyalty platform is authoritative. - `order_payload`: decimal dollars, for the loyalty platform's order endpoint. Submit it verbatim. #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | Body failed validation; `issues[]` says where | | 401 | `UNAUTHORIZED` | Missing or invalid credential, or `?api_key=` in production | | 409 | `OFFERS_RESERVED` | With `lock`: another in-flight order holds one of the single-use offers. Carries `conflict_offer_ids`. Evaluate again; the next result prices without that offer | | 409 | `EVALUATION_TERMINAL` | With `lock`: this `evaluation_id` is already `committed`, `cancelled`, `rolled_back` or `expired`. Carries `state`. Start a new `evaluation_id` | | 503 | `OFFERS_UNAVAILABLE` | The catalog or the vendor's policy could not be read. Retryable; proceed without discounts | ### GET /v1/offers List the vendor's offers without pricing a cart, for a rewards screen. **Auth:** Vendor API key, or OIDC service identity. #### Query parameters | Name | Type | Description | |---|---|---| | `customer` | string | Loyalty customer identifier | | `store_id` | string | Store | | `channel` | string | Channel | Code-gated offers are never listed. There is no status or reason here; call `POST /v1/evaluate` with `selection_mode: "list"` for that. #### Example request ```bash curl "https://offers.spoonity.com/v1/offers?customer=cust_1001&channel=kiosk" \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response ```json { "offers": [ { "offer_id": "reward_free_cookie", "name": "Free Cookie (150 pts)", "cost_points": 150, "pos_reference": "discount_free_cookie", "effect_type": "free_item", "requires_code": false }, { "offer_id": "promo_DRINKS20", "name": "20% off drinks", "pos_reference": "discount_promo_DRINKS20", "effect_type": "percent_off", "requires_code": false }, { "offer_id": "promo_SPEND20", "name": "Spend more, save more", "pos_reference": "discount_promo_SPEND20", "effect_type": "tiered", "requires_code": false }, { "offer_id": "promo_LUNCHCOMBO", "name": "Lunch combo $10.99", "pos_reference": "discount_promo_LUNCHCOMBO", "effect_type": "bundle", "requires_code": false } ] } ``` #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | Invalid query parameter | | 401 | `UNAUTHORIZED` | Missing or invalid credential | ### GET /v1/redemptions/{id} Read one redemption record. **Auth:** Vendor API key, or OIDC service identity. A redemption that belongs to another vendor is a `404`, the same as one that does not exist. #### Path parameters | Name | Description | |---|---| | `id` | `redemption_id` from a locked evaluate (`ored_...`) | #### Example request ```bash curl https://offers.spoonity.com/v1/redemptions/ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0 \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response The redemption from the locked evaluate above, after the order was submitted: ```json { "redemption": { "redemption_id": "ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0", "vendor_id": "dev-vendor", "evaluation_id": "K12-000482", "state": "committed", "offers": [ { "offer_id": "reward_free_cookie", "version": 3, "pos_reference": "discount_free_cookie", "discount_total": 199, "single_use": false, "line_discounts": [ { "id": "discount_free_cookie", "name": "Free Cookie (150 pts)", "amount": 199, "offer_id": "reward_free_cookie", "unit_index": 0, "quantity": 1, "line_id": "2" } ] }, { "offer_id": "promo_WELCOME3", "version": 1, "pos_reference": "discount_promo_WELCOME3", "discount_total": 300, "single_use": false, "allocations": [{ "line_id": "1", "offer_id": "promo_WELCOME3", "amount": 300 }] } ], "cart_snapshot": { "line_items": [ { "line_id": "1", "id": "cola", "name": "Cola", "categories": [{ "id": "drinks" }], "price": 279, "quantity": 2, "discounts": [] }, { "line_id": "2", "id": "cookie", "name": "Cookie", "categories": [{ "id": "desserts" }], "price": 199, "quantity": 1, "discounts": [{ "id": "discount_free_cookie", "name": "Free Cookie (150 pts)", "amount": 199, "offer_id": "reward_free_cookie", "unit_index": 0, "quantity": 1 }] } ], "discounts": [{ "id": "discount_promo_WELCOME3", "name": "$3 Off with Code WELCOME3", "amount": 300, "offer_id": "promo_WELCOME3" }], "allocations": [{ "line_id": "1", "offer_id": "promo_WELCOME3", "amount": 300 }], "subtotal": 757, "discount_total": 499, "total": 258 }, "customer_id": "cust_1001", "created_at": 1790764219390, "expires_at": 1790764519390, "revision": 3, "lock_key": "lock_73effdbf-a2b9-463c-b462-0a2a03032669", "committed_at": 1790764226347, "order_reference": "ord_88213" } } ``` `vendor_id` is the vendor the key belongs to. `mismatch` appears when the submitted order's discount ids differed from what was evaluated; the record still commits. `rolled_back_at`, `cancelled_at` and `returned_line_ids` appear once set. #### Errors | Status | Code | When | |---|---|---| | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 404 | `NOT_FOUND` | No such redemption for this vendor | ### POST /v1/redemptions/{id}/rollback Void a redemption: the order was refunded or voided. Single-use offers, usage counts and budget come back. **Auth:** Vendor API key, or OIDC service identity. A committed or partially returned record becomes `rolled_back`; a pending one becomes `cancelled`. Calling it again is safe. A state that does not allow the transition is returned unchanged. #### Example request ```bash curl -X POST https://offers.spoonity.com/v1/redemptions/ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0/rollback \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response ```json { "redemption": { "redemption_id": "ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0", "state": "rolled_back" } } ``` #### Errors | Status | Code | When | |---|---|---| | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 404 | `NOT_FOUND` | No such redemption for this vendor | ### POST /v1/redemptions/{id}/cancel Cancel a pending redemption and release its hold: the guest abandoned the order. A cancelled record can never commit. **Auth:** Vendor API key, or OIDC service identity. Only a `pending` record changes; any other state is returned unchanged. #### Example request ```bash curl -X POST https://offers.spoonity.com/v1/redemptions/ored_bbfb7ca3-21c8-48aa-9dc3-137047d550fe/cancel \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response ```json { "redemption": { "redemption_id": "ored_bbfb7ca3-21c8-48aa-9dc3-137047d550fe", "state": "cancelled" } } ``` #### Errors | Status | Code | When | |---|---|---| | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 404 | `NOT_FOUND` | No such redemption for this vendor | ### POST /v1/redemptions/{id}/returns Record a partial return by line. Reports the discount that was on each returned line, for a refund clawback. **Auth:** Vendor API key, or OIDC service identity. #### Request body | Field | Type | Required | Description | |---|---|---|---| | `line_ids` | string[] | Yes | 1 to 200 `line_id` values from the evaluated cart. A line already returned contributes nothing the second time | The record becomes `partially_returned`. Single-use offers are not restored and the budget is not refunded: that money left the business on a paid order. Use rollback for a full void. #### Example request ```bash curl -X POST https://offers.spoonity.com/v1/redemptions/ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0/returns \ -H "X-API-Key: YOUR_OFFERS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "line_ids": ["2"] }' ``` #### Example response ```json { "redemption": { "redemption_id": "ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0", "state": "partially_returned" }, "returned": [{ "line_id": "2", "offer_id": "reward_free_cookie", "discount_amount": 199 }] } ``` #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | `line_ids` missing or empty | | 400 | `UNKNOWN_LINES` | Some ids are not in this redemption. Carries `unknown_line_ids` | | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 404 | `NOT_FOUND` | No such redemption for this vendor | | 409 | `INVALID_STATE` | The record is not `committed` or `partially_returned` | ### DELETE /v1/locks/{key} Release a lock and cancel its redemption: the guest cancelled before paying. **Auth:** Vendor API key, or OIDC service identity. #### Path parameters | Name | Description | |---|---| | `key` | `lock.key` from a locked evaluate (`lock_...`) | #### Example request ```bash curl -X DELETE https://offers.spoonity.com/v1/locks/lock_2cbb388d-4c86-490e-b9a0-7c71aea9154d \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response ```json { "released": true, "redemption": { "redemption_id": "ored_e7bf6215-68bd-470f-bf19-f63baa7e2c35", "state": "cancelled" } } ``` #### Errors | Status | Code | When | |---|---|---| | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 404 | `NOT_FOUND` | Unknown, already released or expired lock, or another vendor's | ### POST /webhooks/events How a pending redemption commits or voids: `order.submitted` after an order carrying the `order_payload` lands, and `order.voided` when it is voided. It is correlated on `receipt_number == evaluation_id`. **Auth:** A shared secret in `x-webhook-secret`, held by Spoonity. Not the `/v1` credentials. This route is listed so the lifecycle is complete; an integrator does not call it directly. Before relying on single-use offers or usage limits through `/v1/evaluate`, confirm with Spoonity that these events are being sent for your vendor. The POS check surface does not depend on them: `close` commits directly. | Field | Type | Description | |---|---|---| | `type` | string | `order.submitted` or `order.voided` | | `vendor_id` | string | Vendor | | `receipt_number` | string | The `evaluation_id` | | `discount_ids` | string[] | `order.submitted` only: the discount ids on the order, compared with what was evaluated | | `order_reference` | string | `order.submitted` only: the order id, stored on the record | | `event_id` | string | De-duplication key; a repeated event is a no-op | The answer is always `200` for a valid event, including one whose receipt has no redemption (orders without offers are normal): ```json { "processed": true, "redemption": { "redemption_id": "ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0", "state": "committed", "mismatch": null } } ``` A bad secret is `401 UNAUTHORIZED`. An invalid payload is `400 INVALID_REQUEST`, and on this route `issues[]` is a list of strings rather than `{ path, message }` objects. ## Admin catalog API Manage merchant promotions, the vendor's promotion policy, and read-only loyalty rewards. Prism's Promotions section is built on these routes. Every route is scoped to the calling vendor. A promotion id that belongs to another vendor answers `404`, exactly like one that does not exist. Every non-GET route answers `403 FORBIDDEN` to an OIDC caller with the `viewer` role, except simulate. A promotion is evaluated as the offer `promo_`, and lands on the POS as `pos_reference` (default `discount_promo_`). **Statuses:** `draft` (never evaluated), `active` (live, subject to its own schedule), `paused` (withdrawn, definition kept), `archived` (retired and read-only; never deleted, because redemptions reference its versions). Every write, including a status change, bumps `version` and appends a history entry. There is no delete. **Caching:** evaluation reads the catalog through a cache of up to 5 seconds, so an edit can take that long to affect `POST /v1/evaluate` and the POS check. Admin reads and simulate see it at once. ### The promotion object Request and response bodies use the same field names, so a GET body minus the read-only fields (`promotion_id`, `vendor_id`, `status`, `version`, `created_at`, `updated_at`, `created_by`, `updated_by`) is a valid PUT body. Money is integer cents wherever a field is not a percent. #### Identity and lifecycle | Field | Type | Description | |---|---|---| | `identifier` | string | Optional on create: your id for the promotion. Minted when omitted. `new`, `simulate`, `policy`, `loyalty-rewards`, `history`, `usage`, `.` and `..` are reserved (any case) | | `name` | string | Guest-facing name, 1 to 256 characters. Required | | `notes` | string | Operator note, up to 2000 characters | | `status` | string | On create only: `draft`, `active` or `paused`. Use the lifecycle routes afterwards | | `expected_version` | integer | Required on PUT. Refused on create | | `pos_reference` | string | POS discount identifier. Default `discount_promo_` | #### Effect: `discount_type` Each type accepts only its own fields; a field that belongs to another type is a `400`. | `discount_type` | Fields | Effect | |---|---|---| | `PERCENT` | `discount_amount` (0 to 100), `scope`, `amount_limit`, `max_quantity`, `min_quantity`, `modifier_policy` | Percent off the targeted items (`scope: "item"`) or the order (`scope: "order"`). `amount_limit` caps the total discount in cents | | `AMOUNT` | `discount_amount` (cents), `scope`, `max_quantity`, `min_quantity`, `modifier_policy` | Cents off each targeted unit (`item`) or off the order (`order`) | | `FIXED_PRICE` | `discount_amount` (cents), `max_quantity`, `include_modifiers` | Targeted units sell at this price. By default the price replaces the item price and modifiers are charged on top; `include_modifiers: true` makes it cover item and modifiers | | `FREE_ITEM` | `free_item_sku`, `max_quantity` | Zeroes that SKU when it is in the cart. When it is not, the offer is `applicable` with an `add_item_hint` | | `BUY_X_GET_Y` | `bogo` | Buy the trigger set, get the reward set free or at `percent` off. See below | | `TIERED` | `spend_tiers` | Order-level discount by spend threshold. See below | | `BUNDLE` | `bundle` | Combo price for one complete set of components. See below | Item-scope knobs on `PERCENT` and `AMOUNT`: - `scope`: `item` or `order`. When omitted, `products` or `categories` implies `item`, otherwise `order`. - `max_quantity`: at most this many units discounted per application. - `min_quantity`: apply only with at least this many eligible units, else `MIN_QUANTITY_NOT_MET`. - `modifier_policy`: `include` (default) computes on item plus modifiers; `exclude` on the item price alone. These three are refused on an order-scope effect. `bogo`: ```json { "trigger": { "categories": ["drinks"], "quantity": 1 }, "reward": { "categories": ["drinks"], "quantity": 1, "percent": 100 }, "selection": "cheapest", "max_applications": 2 } ``` `trigger` and `reward` take `products`, `categories`, `exclude_products`, `exclude_categories` and `quantity` (1 to 1000). `reward.percent` defaults to 100. `selection` is `cheapest` (default) or `most_expensive`. `max_applications` is 1 to 100. `spend_tiers` (1 to 20 tiers, distinct `min_spend`): ```json [ { "min_spend": 2000, "amount": 300 }, { "min_spend": 4000, "percent": 15, "amount_limit": 1000 } ] ``` Each tier has exactly one of `percent` or `amount`; `amount_limit` caps a percent tier only. The highest tier reached applies. None reached is `TIER_NOT_REACHED` with `next_min_spend` and `shortfall`. A tiered promotion always discounts the order, so it takes no `scope` and no top-level `products` or `categories`. The field is `spend_tiers`, not `tiers`, because `tiers` is the loyalty-tier restriction below. `bundle`: ```json { "components": [ { "categories": ["mains"], "quantity": 1 }, { "categories": ["sides"], "quantity": 1 }, { "categories": ["drinks"], "quantity": 1 } ], "price": 1099, "max_applications": 1, "selection": "most_expensive" } ``` 1 to 10 components, each with the same item filters as a `bogo` side plus `quantity`. `price` is the combo price in cents. `selection` picks which units fill each component: `cheapest` (default) or `most_expensive`. With `cheapest`, sets are taken until one would not be discounted, so a combo whose cheapest set already costs less than `price` gives nothing even when pricier units are in the cart; choose `most_expensive` if the combo should always apply when the cart is worth more. An incomplete set is `BUNDLE_INCOMPLETE` with `missing[]`. Item filters go on the components; top-level `products` or `categories` are refused. #### Targeting | Field | Type | Description | |---|---|---| | `products` | string[] | SKUs (cart line `id`) that can receive the discount | | `categories` | string[] | Category ids that can receive the discount | | `exclude_products` | string[] | SKUs that never receive it | | `exclude_categories` | string[] | Categories that never receive it | Exclusions win over inclusions. Up to 50 entries each. #### Conditions | Field | Type | Description | |---|---|---| | `min_spend` | integer cents | Minimum subtotal, else `MIN_SPEND_NOT_MET` with `shortfall`. The vendor policy's `min_spend_basis` decides which subtotal | | `tiers` | string[] | Loyalty tier ids allowed, else `TIER_NOT_ELIGIBLE` | | `segments` | string[] | Customer segments allowed, else `CONDITION_NOT_MET` | | `first_order_only` | boolean | Only for a customer with no previous orders. Fails closed when the order count is unknown | | `customer_tags` | string[] | The customer carries at least one of these tags (1 to 50, up to 64 characters each) | | `requires_customer` | boolean | Refuse unidentified guests with `CUSTOMER_REQUIRED`. Default false: promotions are open to guests | #### Schedule and placement | Field | Type | Description | |---|---|---| | `active` | `{ start?, end? }` | ISO 8601 instants with offset. Outside it: `OUTSIDE_ACTIVE_WINDOW` | | `dayparts` | array | `[{ days?, start?, end? }]`. `days` 0 (Sunday) to 6; `start` inclusive and `end` exclusive, `HH:MM` 24-hour. Outside every daypart: `OUTSIDE_DAYPART` | | `stores` | string[] | Store ids allowed, else `STORE_NOT_ELIGIBLE` | | `channels` | string[] | Channels allowed, else `CHANNEL_NOT_ELIGIBLE` | An active promotion outside its daypart, store or channel is still evaluated and reported with the reason, so a screen can say "available from 3pm" rather than hiding it. #### Stacking, redemption and limits | Field | Type | Description | |---|---|---| | `stacking.exclusive` | boolean | Nothing else applies once this does | | `stacking.priority` | integer | -1000 to 1000, default 0. Higher goes first | | `stacking.group` | string | One applied promotion per group | | `requires_code` | string | The code that unlocks it. Without the code the offer is not shown at all | | `auto_apply` | boolean | Applies without being selected in `manual` mode | | `single_use` | boolean | One use per customer. Implies `requires_customer` | | `usage_limits.max_total` | integer | Committed uses across all customers, else `USAGE_LIMIT_REACHED` | | `usage_limits.max_per_customer` | integer | Committed uses per customer. Implies `requires_customer` | | `usage_limits.max_per_day` | integer | Committed uses per UTC day | | `usage_limits.budget_cents` | integer | Total discount this promotion may ever give, else `BUDGET_EXHAUSTED` | | `funding` | string | Who pays: `restaurant` (default), `channel`, `shared`, `loyalty`. Attribution only | | `funding_split.restaurant_bps` | integer | Required when `funding` is `shared`, refused otherwise. Restaurant share, 0 to 10000 basis points | Usage limits and budgets are computed from committed redemptions, so a rollback restores them. #### Response envelope Single-promotion routes answer `{ "promotion": {...}, "offer": {...} }`: the promotion in the wire vocabulary above, and the `offer` the engine actually evaluates. When a promotion does not apply as expected, compare the two. ### GET /v1/admin/promotions List the vendor's promotions. **Auth:** Vendor API key, or OIDC service identity (any role). #### Query parameters | Name | Type | Description | |---|---|---| | `status` | string | `draft`, `active`, `paused` or `archived` | | `limit` | integer | 1 to 500 | #### Example request ```bash curl "https://offers.spoonity.com/v1/admin/promotions?status=active&limit=50" \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response Each entry is the promotion only, without the `offer` projection: ```json { "promotions": [ { "identifier": "SPEND20", "promotion_id": "SPEND20", "vendor_id": "dev-vendor", "name": "Spend more, save more", "status": "active", "version": 1, "pos_reference": "discount_promo_SPEND20", "discount_type": "TIERED", "spend_tiers": [ { "min_spend": 2000, "amount": 300 }, { "min_spend": 4000, "percent": 15, "amount_limit": 1000 } ], "created_at": 1790764191204, "updated_at": 1790764191204 } ] } ``` #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | Invalid `status` or `limit` | | 401 | `UNAUTHORIZED` | Missing or invalid credential | ### POST /v1/admin/promotions Create a promotion. **Auth:** Vendor API key, or OIDC service identity with `admin` or `editor`. #### Request body [The promotion object](#the-promotion-object), without `expected_version`. #### Example request ```bash curl -X POST https://offers.spoonity.com/v1/admin/promotions \ -H "X-API-Key: YOUR_OFFERS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "identifier": "DRINKS20", "name": "20% off drinks", "discount_type": "PERCENT", "discount_amount": 20, "scope": "item", "categories": ["drinks"], "max_quantity": 2, "stacking": { "group": "drinks", "priority": 10 }, "status": "active" }' ``` #### Example response `201`: ```json { "promotion": { "identifier": "DRINKS20", "promotion_id": "DRINKS20", "vendor_id": "dev-vendor", "name": "20% off drinks", "status": "active", "version": 1, "pos_reference": "discount_promo_DRINKS20", "discount_type": "PERCENT", "discount_amount": 20, "scope": "item", "max_quantity": 2, "categories": ["drinks"], "stacking": { "priority": 10, "group": "drinks" }, "created_at": 1790764191191, "updated_at": 1790764191191 }, "offer": { "effect": { "type": "percent_off", "scope": "item", "percent": 20, "max_quantity": 2 }, "targeting": { "categories": ["drinks"] }, "stacking": { "priority": 10, "group": "drinks" }, "offer_id": "promo_DRINKS20", "version": 1, "name": "20% off drinks", "source": { "type": "promotion_code" }, "pos_reference": "discount_promo_DRINKS20" } } ``` A combo, created as a draft so it can be simulated before it goes live: ```bash curl -X POST https://offers.spoonity.com/v1/admin/promotions \ -H "X-API-Key: YOUR_OFFERS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "identifier": "LUNCHCOMBO", "name": "Lunch combo $10.99", "discount_type": "BUNDLE", "bundle": { "components": [ { "categories": ["mains"], "quantity": 1 }, { "categories": ["sides"], "quantity": 1 }, { "categories": ["drinks"], "quantity": 1 } ], "price": 1099, "max_applications": 1, "selection": "most_expensive" }, "channels": ["kiosk", "pos"], "status": "draft" }' ``` #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | Validation failed (see below), `expected_version` sent, or a reserved `identifier` | | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 403 | `FORBIDDEN` | OIDC caller with the `viewer` role | | 409 | `PROMOTION_EXISTS` | The `identifier` is taken. Carries `identifier`. Ids are unique across all vendors, and the message does not say who holds it | A validation failure lists every problem: ```json { "error": { "code": "INVALID_REQUEST", "message": "Promotion validation failed", "issues": [ { "path": "discount_amount", "message": "percent discounts must be between 0 and 100" }, { "path": "min_quantity", "message": "min_quantity applies to item-scoped effects only" } ] } } ``` ### GET /v1/admin/promotions/{id} Read one promotion. **Auth:** Vendor API key, or OIDC service identity (any role). #### Path parameters | Name | Description | |---|---| | `id` | The `promotion_id` | #### Example request ```bash curl https://offers.spoonity.com/v1/admin/promotions/DRINKS20 \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response `{ "promotion": {...}, "offer": {...} }`, the same shape as the create response. #### Errors | Status | Code | When | |---|---|---| | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 404 | `NOT_FOUND` | No such promotion for this vendor | ### PUT /v1/admin/promotions/{id} Replace a promotion. Omitted fields are removed, so send the whole definition: read it, change it, send it back with `expected_version` set to the `version` you read. **Auth:** Vendor API key, or OIDC service identity with `admin` or `editor`. #### Request body [The promotion object](#the-promotion-object) with `expected_version`. `identifier` and `status` are ignored. #### Example request ```bash curl -X PUT https://offers.spoonity.com/v1/admin/promotions/DRINKS20 \ -H "X-API-Key: YOUR_OFFERS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "25% off drinks", "discount_type": "PERCENT", "discount_amount": 25, "scope": "item", "categories": ["drinks"], "max_quantity": 2, "stacking": { "group": "drinks", "priority": 10 }, "expected_version": 1 }' ``` #### Example response ```json { "promotion": { "identifier": "DRINKS20", "promotion_id": "DRINKS20", "vendor_id": "dev-vendor", "name": "25% off drinks", "status": "active", "version": 2, "pos_reference": "discount_promo_DRINKS20", "discount_type": "PERCENT", "discount_amount": 25, "scope": "item", "max_quantity": 2, "categories": ["drinks"], "stacking": { "priority": 10, "group": "drinks" }, "created_at": 1790764191191, "updated_at": 1790764267091 }, "offer": { "effect": { "type": "percent_off", "scope": "item", "percent": 25, "max_quantity": 2 }, "targeting": { "categories": ["drinks"] }, "stacking": { "priority": 10, "group": "drinks" }, "offer_id": "promo_DRINKS20", "version": 2, "name": "25% off drinks", "source": { "type": "promotion_code" }, "pos_reference": "discount_promo_DRINKS20" } } ``` A stale `expected_version` carries the current version and the stored promotion, so a UI can show what changed: ```json { "error": { "code": "VERSION_CONFLICT", "message": "This promotion changed since you read it; re-read and retry", "version": 2, "promotion": { "identifier": "DRINKS20", "promotion_id": "DRINKS20", "vendor_id": "dev-vendor", "name": "25% off drinks", "status": "active", "version": 2, "pos_reference": "discount_promo_DRINKS20", "discount_type": "PERCENT", "discount_amount": 25, "scope": "item", "max_quantity": 2, "categories": ["drinks"], "stacking": { "priority": 10, "group": "drinks" }, "created_at": 1790764191191, "updated_at": 1790764267091 } } } ``` #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | Validation failed | | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 403 | `FORBIDDEN` | OIDC caller with the `viewer` role | | 404 | `NOT_FOUND` | No such promotion for this vendor | | 409 | `VERSION_REQUIRED` | `expected_version` missing. Carries `version`. A missing version is never treated as "overwrite" | | 409 | `VERSION_CONFLICT` | `expected_version` is stale. Carries `version` and `promotion` | | 409 | `PROMOTION_ARCHIVED` | Archived promotions are read-only. Carries `version`. Pause it first to edit it | ### POST /v1/admin/promotions/{id}/activate Set the status to `active`. **Auth:** Vendor API key, or OIDC service identity with `admin` or `editor`. #### Request body Optional: `{ "expected_version": }`. When sent, a stale version is `409 VERSION_CONFLICT`. #### Example request ```bash curl -X POST https://offers.spoonity.com/v1/admin/promotions/LUNCHCOMBO/activate \ -H "X-API-Key: YOUR_OFFERS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "expected_version": 1 }' ``` #### Example response ```json { "promotion": { "identifier": "LUNCHCOMBO", "promotion_id": "LUNCHCOMBO", "vendor_id": "dev-vendor", "name": "Lunch combo $10.99", "status": "active", "version": 2, "pos_reference": "discount_promo_LUNCHCOMBO", "discount_type": "BUNDLE", "bundle": { "components": [ { "categories": ["mains"], "quantity": 1 }, { "categories": ["sides"], "quantity": 1 }, { "categories": ["drinks"], "quantity": 1 } ], "price": 1099, "max_applications": 1, "selection": "most_expensive" }, "channels": ["kiosk", "pos"], "created_at": 1790764191216, "updated_at": 1790764208496 }, "offer": { "effect": { "type": "bundle", "components": [ { "filter": { "categories": ["mains"] }, "quantity": 1 }, { "filter": { "categories": ["sides"] }, "quantity": 1 }, { "filter": { "categories": ["drinks"] }, "quantity": 1 } ], "price": 1099, "max_applications": 1, "selection": "most_expensive" }, "channels": ["kiosk", "pos"], "offer_id": "promo_LUNCHCOMBO", "version": 2, "name": "Lunch combo $10.99", "source": { "type": "promotion_code" }, "pos_reference": "discount_promo_LUNCHCOMBO" } } ``` #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | `expected_version` is not an integer | | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 403 | `FORBIDDEN` | OIDC caller with the `viewer` role | | 404 | `NOT_FOUND` | No such promotion for this vendor | | 409 | `VERSION_CONFLICT` | `expected_version` is stale | ### POST /v1/admin/promotions/{id}/pause Set the status to `paused`. Also the way to un-archive a promotion. **Auth:** Vendor API key, or OIDC service identity with `admin` or `editor`. Same body, response and errors as [activate](#post-v1adminpromotionsidactivate). #### Example request ```bash curl -X POST https://offers.spoonity.com/v1/admin/promotions/DRINKS20/pause \ -H "X-API-Key: YOUR_OFFERS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "expected_version": 2 }' ``` #### Example response `{ "promotion": {...}, "offer": {...} }` with `"status": "paused"` and `"version": 3`. #### Errors As for [activate](#post-v1adminpromotionsidactivate). ### POST /v1/admin/promotions/{id}/archive Set the status to `archived`. An archived promotion is read-only and never evaluated. It is kept, not deleted, so a disputed redemption can be replayed against the exact rule version that paid out. **Auth:** Vendor API key, or OIDC service identity with `admin` or `editor`. Same body, response and errors as [activate](#post-v1adminpromotionsidactivate). #### Example request ```bash curl -X POST https://offers.spoonity.com/v1/admin/promotions/DRINKS20/archive \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response `{ "promotion": {...}, "offer": {...} }` with `"status": "archived"`. A later PUT answers: ```json { "error": { "code": "PROMOTION_ARCHIVED", "message": "Archived promotions are read-only; restore it with /pause first", "version": 4 } } ``` #### Errors As for [activate](#post-v1adminpromotionsidactivate). ### GET /v1/admin/promotions/{id}/history Every version of a promotion, newest first, each with a full snapshot. **Auth:** Vendor API key, or OIDC service identity (any role). #### Example request ```bash curl https://offers.spoonity.com/v1/admin/promotions/DRINKS20/history \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response Abridged to the two oldest entries; each `promotion` is the full snapshot in the wire vocabulary. ```json { "history": [ { "version": 2, "status": "active", "change": "updated", "at": 1790764267091, "promotion": { "identifier": "DRINKS20", "promotion_id": "DRINKS20", "name": "25% off drinks", "version": 2, "discount_amount": 25 } }, { "version": 1, "status": "active", "change": "created", "at": 1790764191191, "promotion": { "identifier": "DRINKS20", "promotion_id": "DRINKS20", "name": "20% off drinks", "version": 1, "discount_amount": 20 } } ] } ``` `change` is `created`, `updated` or `status_changed`. `by` appears when the change was made by a named person (an OIDC call with `X-Spoonity-User`); an API key leaves it out. #### Errors | Status | Code | When | |---|---|---| | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 404 | `NOT_FOUND` | No such promotion for this vendor | ### POST /v1/admin/promotions/simulate Evaluate any cart against the vendor's promotions with no side effects: nothing is reserved or recorded. Use it to check a draft before activating it. **Auth:** Vendor API key, or OIDC service identity (any role, including `viewer`). #### Request body | Field | Type | Required | Description | |---|---|---|---| | `cart` | object | Yes | Same as `POST /v1/evaluate` | | `customer` | object | | What-if customer: `customer_id`, `tier_id`, `segments`, `order_count`, `tags`, `balances: [{ currency_id, balance }]`, and `identifier` to resolve a real customer first. The what-if fields win over what the real customer has | | `codes`, `selected`, `selection_mode`, `channel`, `store_id` | | | Same as `POST /v1/evaluate` | | `now` | ISO 8601 | | Evaluate as of this instant (dayparts, active windows). Default now | | `include_drafts` | boolean | | Add the vendor's `draft` promotions to the candidates | | `promotion_ids` | string[] | | Evaluate exactly these promotions, whatever their status, and no loyalty rewards | | `evaluation_id` | string | | Echoed back. Default `sim_` | The vendor's saved policy and the usage limits apply, read-only. #### Example request ```bash curl -X POST https://offers.spoonity.com/v1/admin/promotions/simulate \ -H "X-API-Key: YOUR_OFFERS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "cart": { "line_items": [ { "line_id": "1", "id": "burger", "name": "Classic Burger", "categories": [{ "id": "mains" }], "price": 899, "quantity": 1 }, { "line_id": "2", "id": "fries", "name": "Fries", "categories": [{ "id": "sides" }], "price": 349, "quantity": 1 }, { "line_id": "3", "id": "cola", "name": "Cola", "categories": [{ "id": "drinks" }], "price": 279, "quantity": 2 }, { "line_id": "4", "id": "cookie", "name": "Cookie", "categories": [{ "id": "desserts" }], "price": 199, "quantity": 1 } ] }, "channel": "kiosk", "include_drafts": true, "now": "2026-10-02T17:00:00Z" }' ``` #### Example response The response is the evaluate result (`evaluation_id`, `offers`, `cart`, `effects`, `receipt_lines`) plus `explain` and `simulation`. Here nothing is selected in `manual` mode, so every eligible promotion is `applicable` with its standalone value. Abridged: `cart.line_items` is omitted and `explain` shows three of its five entries. ```json { "evaluation_id": "sim_33bf90b3-5021-4b35-b76f-56f2029a5803", "offers": [ { "offer_id": "reward_free_cookie", "name": "Free Cookie (150 pts)", "status": "inapplicable", "source": { "type": "redemption", "vendor_perk_redemption_id": 501 }, "pos_reference": "discount_free_cookie", "cost_points": 150, "reason": { "code": "INSUFFICIENT_BALANCE", "message": "Not enough points for this reward", "required": 150, "balance": 0 } }, { "offer_id": "promo_DRINKS20", "name": "20% off drinks", "status": "applicable", "source": { "type": "promotion_code" }, "pos_reference": "discount_promo_DRINKS20", "discount_total": 112 }, { "offer_id": "promo_SPEND20", "name": "Spend more, save more", "status": "applicable", "source": { "type": "promotion_code" }, "pos_reference": "discount_promo_SPEND20", "discount_total": 300 }, { "offer_id": "promo_LUNCHCOMBO", "name": "Lunch combo $10.99", "status": "applicable", "source": { "type": "promotion_code" }, "pos_reference": "discount_promo_LUNCHCOMBO", "discount_total": 428 } ], "cart": { "discounts": [], "allocations": [], "subtotal": 2005, "discount_total": 0, "total": 2005 }, "effects": [], "receipt_lines": [], "explain": [ { "offer_id": "promo_WELCOME3", "name": "$3 Off with Code WELCOME3", "status": "inapplicable", "reason": { "code": "CODE_REQUIRED", "message": "Enter the promotion code to see this offer" }, "promotion_id": "WELCOME3", "promotion_status": "active" }, { "offer_id": "promo_DRINKS20", "name": "20% off drinks", "status": "applicable", "discount_total": 112, "promotion_id": "DRINKS20", "promotion_status": "active" }, { "offer_id": "promo_LUNCHCOMBO", "name": "Lunch combo $10.99", "status": "applicable", "discount_total": 428, "promotion_id": "LUNCHCOMBO", "promotion_status": "draft" } ], "simulation": { "now": "2026-10-02T17:00:00.000Z", "include_drafts": true, "policy_version": null } } ``` `explain` has one entry per candidate. It includes code-gated promotions whose code was not entered (as `CODE_REQUIRED`), which `offers` leaves out. `arbitration_rank` (1-based) appears on offers arbitration tried to apply (`applied` or `skipped`). `policy_version` is `null` when the vendor has no saved policy. #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | Validation failed, or a `promotion_ids` entry is unknown or another vendor's (listed in `unknown_promotion_ids`) | | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 503 | `OFFERS_UNAVAILABLE` | The catalog or policy could not be read | ### GET /v1/admin/promotions/{id}/usage Uses and discount given for one promotion, from the redemption ledger. **Auth:** Vendor API key, or OIDC service identity (any role). #### Query parameters | Name | Type | Description | |---|---|---| | `days` | integer | 1 to 90, default 30. Length of the `per_day` series | `uses` and `discount_cents` are all-time and count `committed` and `partially_returned` records, the same way the usage limits do. `per_day` is zero-filled, oldest first, in UTC days. `limits` echoes `usage_limits` (or `null`); `budget` is `null` without a `budget_cents`. #### Example request ```bash curl "https://offers.spoonity.com/v1/admin/promotions/WELCOME3/usage?days=3" \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response ```json { "promotion_id": "WELCOME3", "offer_id": "promo_WELCOME3", "uses": 2, "discount_cents": 600, "per_day": [ { "day": "2026-09-28", "uses": 0, "discount_cents": 0 }, { "day": "2026-09-29", "uses": 0, "discount_cents": 0 }, { "day": "2026-09-30", "uses": 2, "discount_cents": 600 } ], "window": { "days": 3, "since": "2026-09-28", "until": "2026-09-30" }, "limits": { "max_per_day": 100, "budget_cents": 50000 }, "budget": { "budget_cents": 50000, "spent_cents": 600, "remaining_cents": 49400 } } ``` #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | `days` out of range | | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 404 | `NOT_FOUND` | No such promotion for this vendor | | 503 | `OFFERS_UNAVAILABLE` | The redemption ledger is not available | ### GET /v1/admin/promotions/{id}/redemptions Recent redemption records holding this promotion, in every state, newest first. **Auth:** Vendor API key, or OIDC service identity (any role). #### Query parameters | Name | Type | Description | |---|---|---| | `limit` | integer | 1 to 200, default 50 | | `before` | string | The previous page's `next_before`, or an epoch-millisecond instant | `next_before` is `null` on the last page. `customer_id`, `order_reference`, `committed_at`, `rolled_back_at`, `cancelled_at`, `mismatch` and `returned_line_ids` appear only when set. #### Example request ```bash curl "https://offers.spoonity.com/v1/admin/promotions/WELCOME3/redemptions?limit=1" \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response ```json { "redemptions": [ { "redemption_id": "ored_cc3e0ab9-63f8-4697-8b06-544bb832b6d7", "evaluation_id": "K12-000491", "state": "committed", "order_reference": "ord_88491", "discount_cents": 300, "offer_version": 1, "pos_reference": "discount_promo_WELCOME3", "cart": { "subtotal": 757, "discount_total": 300, "total": 457 }, "created_at": 1790764254348, "expires_at": 1790764554348, "committed_at": 1790764254365 } ], "next_before": "1790764254348:ored_cc3e0ab9-63f8-4697-8b06-544bb832b6d7" } ``` #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | Invalid `limit` or `before` | | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 404 | `NOT_FOUND` | No such promotion for this vendor | | 503 | `OFFERS_UNAVAILABLE` | The redemption ledger is not available | ### The promotion policy One policy per vendor sets the stacking and safety rules for every evaluation of that vendor's carts: `POST /v1/evaluate`, the POS check and simulate. A vendor that never saved one gets the defaults at `version: 0`. | Setting | Values | Default | Effect | |---|---|---|---| | `max_applied_offers` | 1 to 50 | 5 | Most offers applied to one order. Beyond it: `MAX_OFFERS_REACHED` | | `order_percent_mode` | `cascade`, `additive` | `cascade` | `cascade`: each order-level percent applies to what the previous ones left. `additive`: each applies to the same post-item-discount base | | `max_order_discount_percent` | 0 to 100 | none | Ceiling on the order's total discount as a percent of subtotal. Order-level discounts are trimmed, last applied first (`ORDER_CAP_REACHED`); item discounts are never trimmed | | `excluded` | `{ products?, categories?, exclude_products?, exclude_categories? }` | none | Items no promotion may touch (gift cards, alcohol, deposits): never discounted, never counted in an order-level base | | `min_spend_basis` | `subtotal`, `eligible` | `subtotal` | What `min_spend` and spend tiers compare against. `eligible` is the subtotal minus excluded items and POS discounts | | `local_discount_policy` | `respect`, `ignore` | `respect` | `respect`: a line carrying a POS discount gets no item-level offer (`LOCALLY_DISCOUNTED`). `ignore`: it stays discountable, capped at what the POS left | A PUT replaces the whole policy; a setting left out goes back to its default. A GET body minus `vendor_id`, `version`, `updated_at` and `updated_by` is a valid PUT body. ### GET /v1/admin/promotion-policy Read the vendor's policy. **Auth:** Vendor API key, or OIDC service identity (any role). #### Example request ```bash curl https://offers.spoonity.com/v1/admin/promotion-policy \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response Before any save: ```json { "policy": { "vendor_id": "dev-vendor", "version": 0, "updated_at": 0, "max_applied_offers": 5, "order_percent_mode": "cascade", "min_spend_basis": "subtotal", "local_discount_policy": "respect" }, "saved": false } ``` #### Errors | Status | Code | When | |---|---|---| | 401 | `UNAUTHORIZED` | Missing or invalid credential | ### PUT /v1/admin/promotion-policy Replace the vendor's policy. **Auth:** Vendor API key, or OIDC service identity with `admin` or `editor`. #### Request body The settings in the table above, plus `expected_version`: `0` for the first save, otherwise the `version` you read. Unknown keys, including the read-only record fields, are a `400`. #### Example request ```bash curl -X PUT https://offers.spoonity.com/v1/admin/promotion-policy \ -H "X-API-Key: YOUR_OFFERS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "expected_version": 0, "max_applied_offers": 3, "order_percent_mode": "additive", "max_order_discount_percent": 50, "excluded": { "categories": ["gift_cards", "alcohol"] }, "min_spend_basis": "eligible", "local_discount_policy": "respect" }' ``` #### Example response ```json { "policy": { "vendor_id": "dev-vendor", "version": 1, "updated_at": 1790764275951, "max_applied_offers": 3, "order_percent_mode": "additive", "min_spend_basis": "eligible", "local_discount_policy": "respect", "max_order_discount_percent": 50, "excluded": { "categories": ["gift_cards", "alcohol"] } }, "saved": true } ``` #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | Validation failed | | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 403 | `FORBIDDEN` | OIDC caller with the `viewer` role | | 409 | `VERSION_REQUIRED` | `expected_version` missing. Carries the current `version` | | 409 | `VERSION_CONFLICT` | `expected_version` is stale. Carries `version` and the stored `policy` | ### GET /v1/admin/promotion-policy/history Every saved version of the policy, newest first. **Auth:** Vendor API key, or OIDC service identity (any role). #### Example request ```bash curl https://offers.spoonity.com/v1/admin/promotion-policy/history \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response ```json { "history": [ { "version": 1, "at": 1790764275951, "policy": { "vendor_id": "dev-vendor", "version": 1, "updated_at": 1790764275951, "max_applied_offers": 3, "order_percent_mode": "additive", "min_spend_basis": "eligible", "local_discount_policy": "respect", "max_order_discount_percent": 50, "excluded": { "categories": ["gift_cards", "alcohol"] } } } ] } ``` `by` appears on an entry saved by a named person. #### Errors | Status | Code | When | |---|---|---| | 401 | `UNAUTHORIZED` | Missing or invalid credential | ### GET /v1/admin/loyalty-rewards The vendor's loyalty rewards, read-only, so they can be shown beside the promotions they stack with. They are edited in the loyalty program, not here. **Auth:** Vendor API key, or OIDC service identity (any role). The response has three parts: - `rewards`: the rewards the engine prices, in the engine's offer shape. These are exactly what arbitration sees. A loyalty reward's discount applies to one line: a percent or amount reward is item-scoped with `max_quantity: 1`. - `unpriced`: active loyalty rewards the engine cannot price. They never enter arbitration, and are listed so they are not silently missing. Each has a `reason`: - `POS_PRICED`: no discount definition, and a catalog identifier starting with `discount_` or `clover_`. The POS prices it by catalog code (Clover, for example, rings it as 100% off the line the cashier picks), which the engine cannot do because it cannot pick the line. - `NO_DISCOUNT_DEFINITION`: no discount definition and any other identifier. - `UNSUPPORTED_DISCOUNT`: a discount definition this service cannot read. - `loyalty.connected`: whether this vendor's loyalty program is connected to Offers. A vendor without a connection gets `200` with empty lists and `connected: false`; that is not an error. Inactive rewards, Loyalty Pay (a tender, not a discount) and information-only rows appear in neither list. `unpriced` entries: | Field | Type | Description | |---|---|---| | `vendor_perk_redemption_id` | integer | The reward's id in the loyalty program | | `name` | string | Reward name | | `catalog_identifier` | string | The loyalty catalog identifier (the POS code), when the reward has one | | `pos_reference` | string | `discount_`, with the identifier exactly as the loyalty program sends it, and not doubled when it already starts with `discount_` | | `cost_points` | integer | Point cost, when the reward has one | | `pos_ids` | string[] | POS ids, ascending, when the reward's data is keyed by point of sale | | `reason` | string | `POS_PRICED`, `NO_DISCOUNT_DEFINITION` or `UNSUPPORTED_DISCOUNT` | #### Example request ```bash curl https://offers.spoonity.com/v1/admin/loyalty-rewards \ -H "X-API-Key: YOUR_OFFERS_API_KEY" ``` #### Example response A connected vendor with one priced reward and two the engine cannot price: ```json { "rewards": [ { "offer_id": "off_r12617", "version": 1, "name": "New Member Half Off", "source": { "type": "redemption", "vendor_perk_redemption_id": 12617 }, "pos_reference": "discount_16ozHalfOffEspresso", "effect": { "type": "percent_off", "scope": "item", "percent": 50, "max_quantity": 1 }, "stacking": { "exclusive": false, "priority": 0 }, "cost_points": 100 } ], "unpriced": [ { "vendor_perk_redemption_id": 1644, "name": "Welcome Reward", "catalog_identifier": "discount_reward300", "pos_reference": "discount_reward300", "cost_points": 30000, "reason": "POS_PRICED" }, { "vendor_perk_redemption_id": 8346, "name": "Drip Tea", "catalog_identifier": "DripTea", "pos_reference": "discount_DripTea", "cost_points": 5000, "reason": "NO_DISCOUNT_DEFINITION" } ], "loyalty": { "connected": true } } ``` Not connected: ```json { "rewards": [], "unpriced": [], "loyalty": { "connected": false } } ``` #### Errors | Status | Code | When | |---|---|---| | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 503 | `OFFERS_UNAVAILABLE` | Connected, but the loyalty platform failed (error or timeout). Retryable | ## Loyalty order outbox When Spoonity forwards closed POS checks to the loyalty program, each close (and each void of a closed check) is a row in an outbox that a background worker posts to the merchant's loyalty platform. These two admin endpoints show the rows and revive failed ones. They need an API key like the other `/v1/admin/*` routes, and they only ever show the key's own vendor. ### GET /v1/admin/loyalty-outbox Newest rows first. #### Query parameters | Name | Type | Required | Description | |---|---|---|---| | `state` | string | | `pending`, `sent`, `dead` or `skipped` | | `limit` | integer | | 1 to 200. Default 50 | Any other parameter is a `400`. States: - `pending`: waiting to be sent, or waiting to be retried. - `sent`: the loyalty platform accepted it. - `dead`: not retried automatically. A 4xx answer, a business error in the platform's answer, 8 failed attempts, or a void whose order is dead. - `skipped`: recorded and never sent (`skip_reason`): `NO_CUSTOMER` (a guest), `CHECK_VOIDED`, `FORWARD_DISABLED`, `NO_LOYALTY_KEY` or `ORDER_SKIPPED` (a void whose order was skipped). #### Example request ```bash curl "https://offers.spoonity.com/v1/admin/loyalty-outbox?state=dead&limit=20" \ -H "X-API-Key: YOUR_API_KEY" ``` #### Example response ```json { "items": [ { "id": "lob_0c1d2e3f", "vendor_id": "2112901", "kind": "order", "dedupe_key": "order:2112901:20261103-104202:1042-20261103-104202", "receipt_number": "2112901-20261103-104202", "store_id": "2112901", "check_id": "20261103-104202", "pos_transaction_id": "1042-20261103-104202", "body": { "receipt_number": "2112901-20261103-104202", "card_number": "6040123412341234", "subtotal": 13.98, "total": 6.07 }, "state": "dead", "attempts": 8, "next_attempt_at": 1793712970000, "last_error": "loyalty-api answered 503", "last_status": 503, "created_at": 1793712970000, "updated_at": 1793716570000 } ] } ``` `body` is the request sent to the loyalty platform (shortened here). Times are epoch milliseconds. #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | A bad query parameter | | 401 | `UNAUTHORIZED` | Missing or invalid credential | ### POST /v1/admin/loyalty-outbox/{id}/retry Move a `dead` row back to `pending`, with its attempts reset and due now. Retrying an order also revives the voids that died only because that order was dead. Needs the admin role; a read-only role cannot retry. #### Example request ```bash curl -X POST https://offers.spoonity.com/v1/admin/loyalty-outbox/lob_0c1d2e3f/retry \ -H "X-API-Key: YOUR_API_KEY" ``` The response is `{ "item": { ... } }` with the row as above and `state: "pending"`, plus `revived_voids` (a list of row ids) when voids were revived. #### Errors | Status | Code | When | |---|---|---| | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 403 | `FORBIDDEN` | Read-only role | | 404 | `NOT_FOUND` | No such row for this vendor | | 409 | `NOT_RETRYABLE` | The row is not `dead`. `state` says what it is | A row whose loyalty-api key was revoked dies with a `last_error` that starts with `KEY_REVOKED`. Retrying it only helps once the key is restored (below) or replaced. A row sent with a store's own key carries `key_hash`, the SHA-256 of that key (never the key). ## POS keys The store keys Offers has learned from POS traffic, and the keys the loyalty program has stopped accepting. Admin role only (a `viewer` or `editor` role is `403`), and only ever the authenticated merchant's keys. The key itself is never returned: a key is named by the first 12 hex characters of its SHA-256. A key is revoked when any loyalty program call made with it answers that the key is unknown, not active, expired or that its vendor is not active. Network errors, timeouts and other errors never revoke a key. A revoked store key is refused (`401` on the POS API) and its stored copy is deleted. A revoked merchant key from Spoonity's configuration is refused too, and the merchant's loyalty rewards are unavailable until Spoonity replaces it in its configuration (an alert fires). ### GET /v1/admin/pos-keys Newest first. #### Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | 1 to 200. Default 50 | #### Example request ```bash curl "https://offers.spoonity.com/v1/admin/pos-keys" \ -H "X-API-Key: YOUR_API_KEY" ``` #### Example response ```json { "items": [ { "key_hash_prefix": "3f9a1c0b7d2e", "kind": "learned", "store_vendor_id": "2112905", "master_vendor_id": "2112901", "status": "revoked", "revoked_reason": "KEY_NOT_ACTIVE", "first_seen_at": "2026-11-03T08:00:04.120Z", "last_seen_at": "2026-11-05T21:14:40.002Z", "last_validated_at": "2026-11-05T08:00:11.734Z" } ] } ``` `kind` is `learned` (a store key) or `configured` (a merchant key from Spoonity's configuration). `status` is `active` or `revoked`. `revoked_reason` is `KEY_UNKNOWN`, `KEY_NOT_ACTIVE`, `KEY_NOT_FOUND` or `VENDOR_NOT_ACTIVE`. Active store keys are checked again with the loyalty program every 24 hours. ### POST /v1/admin/pos-keys/{hash}/restore Check a revoked key with the loyalty program now, and accept it again if the program does. `{hash}` is the `key_hash_prefix` from the listing (or more of the hash). - A merchant key: checked with the key from Spoonity's configuration. - A store key: its stored copy was deleted when it was revoked. Send the key in the body, `{ "key": "..." }`, to check it now. Without a body the revocation is cleared and the key is checked again, like a new key, on its next POS request (`status: "cleared"`). #### Example request ```bash curl -X POST https://offers.spoonity.com/v1/admin/pos-keys/3f9a1c0b7d2e/restore \ -H "X-API-Key: YOUR_API_KEY" ``` #### Example response ```json { "status": "cleared", "item": { "key_hash_prefix": "3f9a1c0b7d2e", "kind": "learned", "store_vendor_id": "2112905", "master_vendor_id": "2112901", "status": "revoked", "revoked_reason": "KEY_NOT_ACTIVE", "first_seen_at": "2026-11-03T08:00:04.120Z", "last_seen_at": "2026-11-05T21:14:40.002Z", "last_validated_at": "2026-11-05T08:00:11.734Z" } } ``` `status` is `restored` (checked and accepted again) or `cleared`. #### Errors | Status | Code | When | |---|---|---| | 400 | `KEY_MISMATCH` | The `key` sent does not match the hash | | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 403 | `FORBIDDEN` | Not the admin role | | 404 | `NOT_FOUND` | No such key for this merchant | | 409 | `AMBIGUOUS` | More than one key starts with this prefix | | 409 | `NOT_REVOKED` | The key is not revoked | | 409 | `STILL_REJECTED` | The loyalty program still does not accept the key. `reason` says why | | 409 | `FOREIGN_MASTER` | The key belongs to another merchant | | 503 | `UPSTREAM_UNAVAILABLE` | The loyalty program could not be reached. Retry | ## POS check API For a POS that sends the whole check at pay time and wants the discount back. The customer's app QR, a customer id or phone number, or a coupon code can go on the check. Spoonity reprices it with the vendor's promotions, rewards and policy, holds single-use rewards for 15 minutes, and returns one subtotal discount plus the per-line detail. The POS applies it, takes payment, and posts `close`. 1. **Pay pressed:** `POST /partners/pos/check` with the full check. Send it again if the cart changes; each call replaces the hold. 2. **Apply** `subtotal_discount` as one subtotal discount, or each `discounts[]` entry on its line. Take payment. 3. **Check closed:** `POST /partners/pos/close`, always, even when `check` failed or timed out. 4. **Refund or void:** `POST /partners/pos/void`. Optionally, `GET /partners/pos/offers` fills a cashier prompt after a scan. **Base path:** `https://offers.spoonity.com/partners/pos` **Version:** every response carries `X-Spoonity-Api-Version: 2026-10-16`. New request fields are always optional and new response fields can be ignored; nothing documented is removed or changes meaning without a new version. ### Evaluation ids The engine keys a check as `":"`, the store being the POS key's, for example `S12:1042`. That is why neither id may contain a colon. You never send it back; it is returned for support and logs. If a check's hold expires, or it is voided while still open, a later `check` reserves under a new id with a generation suffix: `S12:1042:2`, then `S12:1042:3`. Every later call on that check finds the current one. A check has 10 ids in total. Each expiry, open void and lost race for a single-use reward uses one; after that `check` answers `409 CHECK_REOPEN_LIMIT`. ### Idempotency - `check` is safe to repeat: the same `check_id` from the same store's key always refers to the same hold, replaced with the new cart's result. A re-check that 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. - `void` is idempotent on `pos_transaction_id`, tracked separately from `close`, so a void may reuse the close's transaction id. - A closed check cannot be checked again (`409 CHECK_CLOSED`); a new sale needs a new `check_id`. ### Timeouts and retries - Time out `check` at about 3 seconds. On a timeout, a `5xx` or a network error, close the check without a Spoonity discount. Do not block the cashier. - Retry `close` and `void` on `5xx` or network errors, with backoff. They are idempotent. - Do not retry a `4xx`. The one exception is `409 OFFERS_RESERVED`: another check won the race for the same single-use reward three times inside this one request. Re-send `check` once, and if it fails again, proceed without a discount. - `503 OFFERS_UNAVAILABLE` on `check`, including a member lookup that failed, means proceed without a discount. Always `close`. `customer_code` (the scanned card number; the simple form of `customer.customer_id`) and `phone` resolve a member only for a merchant whose loyalty program is connected to Offers; otherwise the check is priced with the promotions open to everyone (`customer: null`). A reward the customer picked in the app is applied from the scanned `customer_code` alone (see [App reward picks](#app-reward-picks-api)); the POS does not send its `offer_id`. **Code prefix.** A POS that recognises loyalty codes by a fixed prefix sends the whole code as scanned, prefix included; Spoonity removes the prefix. The prefix is set per merchant during setup and matched exactly, letter case included; a code that does not start with the whole prefix is used as sent. It is removed from `customer_code`, `customer.customer_id` and `customer.phone` on `check` and `close`, and from codes the app registers (`code` on `POST /partners/app/selections`, `PUT /partners/app/code`). ### POST /partners/pos/check Reprice a check and hold its single-use rewards. **Auth:** `Authorization: Bearer` POS key (or `X-Spoonity-POS-Key`). #### Request body | Field | Type | Required | Description | |---|---|---|---| | `check_id` | string | Yes | Your check number. `A-Z a-z 0-9 _ . -`, at most 60 characters, no colon. Must stay unique per store for as long as the check can be refunded; prefix a daily-reset number with the business date | | `lines` | array | Yes | Up to 200 lines, see below | | `customer_code` | string | | The scanned card number, 1 to 128 characters. The simple form of `customer: { "customer_id": ... }`, with identical behaviour. 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, 1 to 128 characters), `phone` (3 to 32 characters) or `qr_token` (1 to 512 characters; not available yet, answers `503 CUSTOMER_LOOKUP_UNAVAILABLE`). Omit for a guest | | `codes` | string[] | | Coupon or promo codes. At most 50 | | `selected_offer_ids` | string[] | | The `offer_id` of each reward or promotion the customer wants to use. At most 50 | | `channel` | string | | Default `pos`. Free-form; recommended `pos`, `dine_in`, `takeout`, `drive_thru`, `delivery`, `kiosk`. Promotions can be limited to channels | | `discounts` | array | | Discounts the POS already took off the whole check: `{ id, name?, amount }`, cents. At most 50. They lock no line | | `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? }`, each 1 to 50 characters. Logged | | `metadata` | object | | Your own fields, ignored by pricing. String keys 1 to 64 characters; values a string up to 256, a number, a boolean or `null`; at most 50 keys | | `terminal_id` | string | | Logged only | | `pos_transaction_id` | string | | Logged only on `check` | A line is `{ line_id, sku, name?, price, quantity, categories?, modifiers?, discounts?, components?, metadata? }`. `price` is the unit price in cents. If the POS prices modifiers separately, send the base price and list the modifiers; if it rolls them into the item price, send the full price and no `modifiers`. A modifier is `{ id, name?, price, quantity, modifiers?, metadata? }`, `quantity` per unit of the line; its own `modifiers` (up to 3 levels deep) have `quantity` per unit of their parent, and every level is priced. `discounts` are discounts the POS already applied to the line: `{ id, name?, amount, source? }`, whole-line cents. Up to 50 categories and 50 discounts per line, and 50 modifiers per line (per component on a combo) counting every level. Unknown fields anywhere except inside `metadata` are a `400`. **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. #### Example request A customer identified by id, a coupon code, and a cookie the register has already discounted: ```bash curl -X POST https://offers.spoonity.com/partners/pos/check \ -H "Authorization: Bearer YOUR_POS_KEY" \ -H "Content-Type: application/json" \ -d '{ "check_id": "1042", "terminal_id": "T1", "customer_code": "cust_1001", "codes": ["WELCOME3"], "selected_offer_ids": ["reward_free_cookie"], "lines": [ { "line_id": "1", "sku": "burger", "name": "Classic Burger", "price": 899, "quantity": 1, "categories": [{ "id": "mains" }] }, { "line_id": "2", "sku": "cola", "name": "Cola", "price": 279, "quantity": 1, "categories": [{ "id": "drinks" }], "modifiers": [{ "id": "large", "name": "Large", "price": 50, "quantity": 1 }] }, { "line_id": "3", "sku": "cookie", "name": "Cookie", "price": 199, "quantity": 1, "categories": [{ "id": "desserts" }], "discounts": [{ "id": "emp", "name": "Employee 50%", "amount": 100 }] } ] }' ``` #### Example response `200`. The code applied. The cookie reward was skipped because the register had already discounted that line (`LOCALLY_DISCOUNTED`). ```json { "evaluation_id": "S12:1042", "check_id": "1042", "customer": { "customer_id": "cust_1001", "balances": [{ "currency_id": "points", "balance": 420 }] }, "subtotal": 1427, "subtotal_discount": 300, "external_discount_total": 100, "total": 1027, "discounts": [ { "pos_reference": "discount_promo_WELCOME3", "offer_id": "promo_WELCOME3", "name": "$3 Off with Code WELCOME3", "amount": 300, "scope": "order", "allocations": [ { "line_id": "1", "amount": 203, "unit_amount": 203 }, { "line_id": "2", "amount": 74, "unit_amount": 74 }, { "line_id": "3", "amount": 23, "unit_amount": 23 } ] } ], "offers": [ { "offer_id": "reward_free_cookie", "name": "Free Cookie (150 pts)", "status": "skipped", "source": { "type": "redemption", "vendor_perk_redemption_id": 501 }, "pos_reference": "discount_free_cookie", "cost_points": 150, "reason": { "code": "LOCALLY_DISCOUNTED", "message": "Eligible items already carry a discount from the register" } }, { "offer_id": "promo_WELCOME3", "name": "$3 Off with Code WELCOME3", "status": "applied", "source": { "type": "promotion_code", "code": "WELCOME3" }, "pos_reference": "discount_promo_WELCOME3", "funding": "restaurant", "discount_total": 300 }, { "offer_id": "promo_SPEND20", "name": "Spend more, save more", "status": "inapplicable", "source": { "type": "promotion_code" }, "pos_reference": "discount_promo_SPEND20", "reason": { "code": "TIER_NOT_REACHED", "message": "Spend $20.00 to unlock", "next_min_spend": 2000, "shortfall": 673 } }, { "offer_id": "promo_LUNCHCOMBO", "name": "Lunch combo $10.99", "status": "applicable", "source": { "type": "promotion_code" }, "pos_reference": "discount_promo_LUNCHCOMBO", "reason": { "code": "BUNDLE_INCOMPLETE", "message": "Add the remaining items to complete this combo", "missing": [{ "component": 1, "required": 1, "available": 0 }] } } ], "receipt_lines": ["$3 Off with Code WELCOME3 applied, you saved $3.00"], "redemption_id": "ored_d768ed3c-503c-453f-a03c-70ae6538695c", "hold_expires_at": "2026-09-30T10:46:31.864Z" } ``` - `subtotal_discount` is the whole Spoonity discount, item and order combined. A POS that takes one number applies it as a subtotal discount. - `discounts[]` sums to `subtotal_discount`. `scope: "item"` entries carry `line_id` (and `component_id` for a part of a combo, `unit_index`, `quantity`); `scope: "order"` entries carry `allocations`, their split by line (and part), which add up to the entry's `amount`. Echo the ones you applied on `close`. - `amount` (on an entry or an allocation) is the total for the units it covers: apply it once. `unit_amount` is that total divided by the units covered (an item entry's `quantity`; every unit of the line or part for an allocation), present only when it divides evenly. A POS that multiplies an item modifier by the line quantity applies `unit_amount` instead, or sends units that get different discounts as separate lines. - `total` is `subtotal` minus `external_discount_total` minus `subtotal_discount`, pre-tax. `external_discount_total` appears only when lines or the check carried POS discounts. - `subtotal_mismatch` (`{ received, computed }`, cents) appears only when the request carried `subtotal` and it differs from `subtotal`. Pricing is unchanged and the status is still 200. Absent when they agree. - `receipt_lines` are display text; the wording can change (the engine separates the two halves with a dash character). - `customer` is `null` for a guest, and for a member the merchant's loyalty program could not match (the check is then priced as a guest). For a member, `balances` holds one entry per loyalty currency, keyed by its currency id, in hundredths. - `hold_expires_at`: single-use rewards are held until then. A `close` after it does not commit (`EVALUATION_EXPIRED`); send `check` again first if a check sits that long. #### Errors | Status | Code | When | POS action | |---|---|---|---| | 400 | `INVALID_REQUEST` | Validation failed: decimals, duplicate `line_id`, unknown fields, a colon in an id, two customer identifiers (including `customer_code` with `customer`), any limit | Fix the integration; do not retry | | 401 | `UNAUTHORIZED` | Missing or unknown POS key, or one the loyalty program no longer accepts | Proceed without discount | | 413 | `PAYLOAD_TOO_LARGE` | The body is over 256 KB | Fix the integration; proceed without discount | | 429 | `RATE_LIMITED` | Too many requests for this key. `Retry-After` gives the seconds to wait | Wait that long and retry; if it does not clear, proceed without discount | | 409 | `CHECK_CLOSED` | The check already closed or was refunded. Carries `state` and `evaluation_id` | New sale, new `check_id` | | 409 | `CHECK_REOPEN_LIMIT` | All 10 evaluation ids used | New `check_id` | | 409 | `OFFERS_RESERVED` | Lost the race for a single-use reward three times | Re-send once, else proceed without discount | | 503 | `OFFERS_UNAVAILABLE` | Promotions, policy or database could not be read, or a member lookup failed | Proceed without discount; always `close` | | 503 | `CUSTOMER_LOOKUP_UNAVAILABLE` | A `customer.qr_token` could not be resolved (not available yet) | Proceed without discount; always `close` | | 500 | `INTERNAL` | A bug on Spoonity's side | As for 503 | ```json { "error": { "code": "CHECK_CLOSED", "message": "This check is already closed; a new sale needs a new check_id", "state": "committed", "evaluation_id": "S12:1042" } } ``` ### POST /partners/pos/close Commit a closed check. Send it once the check is paid, always. **Auth:** `Authorization: Bearer` POS key (or `X-Spoonity-POS-Key`). #### Request body | Field | Type | Required | Description | |---|---|---|---| | `check_id` | string | Yes | As on `check` | | `pos_transaction_id` | string | Yes | Your id for this closed transaction. The idempotency key | | `receipt.discounts` | array | Yes | The Spoonity discounts you actually applied, echoed from `check`: `{ pos_reference, amount, name?, line_id?, component_id?, unit_amount? }` (`unit_amount` is accepted and ignored). Empty if none. Up to 200 | | `receipt.lines` | array | Yes | The final lines, same shape and limits as on `check`. Posted to the loyalty program for points when the forward is on | | `receipt.total` | integer cents | Yes | The receipt total before tax, after every discount. Posted to the loyalty program | | `receipt.pos_discounts` | array | | Your own check-level discounts as applied, `{ id, name?, amount }`. At most 50. Recorded | | `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; not posted (the loyalty program has no field for it) | | `receipt.payments` | array | | `{ method, amount }`, `method` 1 to 64 characters, at most 50. Recorded; not posted (no field for it) | | `receipt.metadata`, `metadata` | object | | Your own fields, as on `check` | | `cashier` | object | | `{ id, name? }`, each 1 to 50 characters. The cashier of the sale in the loyalty program (`name` defaults to the id); absent, the sale names Spoonity Offers | | `customer_code` | string | | As on `check`: the scanned card number, the simple form of `customer: { "customer_id": ... }`. Send `customer_code` or `customer`, not both | | `customer` | object | | The alternative to `customer_code`, as on `check`: exactly one of `customer_id`, `phone`, `qr_token`. Names the customer the sale is posted to the loyalty program for when no earlier `check` for this check identified one; when both did, the one from `check` is used. Never changes the discounts or the commit. A `qr_token` here names no one | | `terminal_id` | string | | When it is 1 to 9 digits, the till number in the loyalty program; otherwise till 0 | | `closed_at` | ISO 8601 with offset | | When the check closed. The 15-minute hold is judged at this time when it is within 24 hours back and 5 minutes ahead of Spoonity's clock (else the arrival time). Its local wall clock dates the sale in the loyalty program; a `Z` time does not | Spoonity commits what the last `check` evaluated; it does not reprice at close. The references and the sum of `receipt.discounts[].amount` are compared with that result. #### Example request ```bash curl -X POST https://offers.spoonity.com/partners/pos/close \ -H "Authorization: Bearer YOUR_POS_KEY" \ -H "Content-Type: application/json" \ -d '{ "check_id": "1042", "pos_transaction_id": "TXN-S12-1042", "terminal_id": "T1", "closed_at": "2026-09-30T12:31:05-04:00", "receipt": { "lines": [ { "line_id": "1", "sku": "burger", "name": "Classic Burger", "price": 899, "quantity": 1, "categories": [{ "id": "mains" }] }, { "line_id": "2", "sku": "cola", "name": "Cola", "price": 279, "quantity": 1, "categories": [{ "id": "drinks" }], "modifiers": [{ "id": "large", "name": "Large", "price": 50, "quantity": 1 }] }, { "line_id": "3", "sku": "cookie", "name": "Cookie", "price": 199, "quantity": 1, "categories": [{ "id": "desserts" }], "discounts": [{ "id": "emp", "name": "Employee 50%", "amount": 100 }] } ], "discounts": [{ "pos_reference": "discount_promo_WELCOME3", "amount": 300 }], "total": 1027 } }' ``` #### Example response ```json { "committed": true, "redemption_id": "ored_d768ed3c-503c-453f-a03c-70ae6538695c", "evaluation_id": "S12:1042" } ``` If what you applied differs from what `check` returned, Spoonity still commits (the money has left the till) and reports the difference: ```json { "committed": true, "redemption_id": "ored_dbde8782-27cb-42ed-b2be-42b2d90f12ef", "evaluation_id": "S12:1043", "mismatch": { "expected_pos_references": ["discount_promo_WELCOME3"], "received_pos_references": ["discount_promo_WELCOME3"], "expected_discount_total": 300, "received_discount_total": 250 } } ``` `committed: false` is still a `200`, so the POS never retries it forever. `reason` says why: | `reason` | Meaning | |---|---| | `NO_PENDING_EVALUATION` | Spoonity never saw a `check` for this check. Nothing to commit. Body: `{ "committed": false, "redemption_id": null, "reason": "NO_PENDING_EVALUATION" }`. The sale is still posted for points when the `close` carries `customer_code` or `customer` | | `EVALUATION_EXPIRED` | The 15-minute hold had lapsed. The reward was not consumed | | `EVALUATION_CANCELLED` | The check was voided while open, or the last `check` answered `409 OFFERS_RESERVED` | | `EVALUATION_ROLLED_BACK` | The transaction was already voided | Apart from `NO_PENDING_EVALUATION`, the body also carries `redemption_id`, `evaluation_id` and `state`. #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | Validation failed | | 401 | `UNAUTHORIZED` | Missing or unknown POS key, or one the loyalty program no longer accepts | | 413 | `PAYLOAD_TOO_LARGE` | The body is over 256 KB | | 429 | `RATE_LIMITED` | Too many requests for this key. See `Retry-After` | | 503 | `OFFERS_UNAVAILABLE` | The database could not be reached. Retry with backoff | ### POST /partners/pos/void Void or refund a closed check, or cancel an open one. Restores single-use rewards, usage counts and budget. **Auth:** `Authorization: Bearer` POS key (or `X-Spoonity-POS-Key`). #### Request body | Field | Type | Required | Description | |---|---|---|---| | `check_id` | string | Yes | As on `check` | | `pos_transaction_id` | string | Yes | Idempotency key for the void | | `terminal_id` | string | | Logged only | Partial refunds are not supported on this surface. #### Example request ```bash curl -X POST https://offers.spoonity.com/partners/pos/void \ -H "Authorization: Bearer YOUR_POS_KEY" \ -H "Content-Type: application/json" \ -d '{ "check_id": "1042", "pos_transaction_id": "TXN-S12-1042" }' ``` #### Example response ```json { "voided": true, "redemption_id": "ored_d768ed3c-503c-453f-a03c-70ae6538695c", "evaluation_id": "S12:1042", "state": "rolled_back" } ``` `voided: true` means nothing is held or consumed for the check any more. `state` is `rolled_back` (it had closed), `cancelled` (it was open) or `expired` (its hold had already lapsed). An unknown check answers `{ "voided": false, "redemption_id": null, "reason": "NO_PENDING_EVALUATION" }`. #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | Validation failed | | 401 | `UNAUTHORIZED` | Missing or unknown POS key, or one the loyalty program no longer accepts | | 413 | `PAYLOAD_TOO_LARGE` | The body is over 256 KB | | 429 | `RATE_LIMITED` | Too many requests for this key. See `Retry-After` | | 503 | `OFFERS_UNAVAILABLE` | The database could not be reached. Retry with backoff | ### GET /partners/pos/offers The promotions open to everyone at a store, for a cashier prompt before the cart is final. Nothing is applied or held. Looking up a member's offers here is not available yet. **Auth:** `Authorization: Bearer` POS key (or `X-Spoonity-POS-Key`). #### Query parameters | Name | Type | Required | Description | |---|---|---|---| | `channel` | string | | Default `pos` | | `customer` | string | | A customer app QR token, 1 to 512 characters. Not available yet: answers `503 CUSTOMER_LOOKUP_UNAVAILABLE` | Any other query parameter is a `400`. Code-gated offers are never listed. Offers outside their schedule are left out. An offer whose cart condition is not met yet carries `needs`, a reason with the shortfall. #### Example request ```bash curl "https://offers.spoonity.com/partners/pos/offers" \ -H "Authorization: Bearer YOUR_POS_KEY" ``` #### Example response A guest, with an empty cart: ```json { "customer": null, "offers": [ { "offer_id": "promo_SPEND20", "name": "Spend more, save more", "pos_reference": "discount_promo_SPEND20", "effect_type": "tiered", "auto_apply": false, "pre_selected": false, "needs": { "code": "TIER_NOT_REACHED", "message": "Spend $20.00 to unlock", "next_min_spend": 2000, "shortfall": 2000 } }, { "offer_id": "promo_LUNCHCOMBO", "name": "Lunch combo $10.99", "pos_reference": "discount_promo_LUNCHCOMBO", "effect_type": "bundle", "auto_apply": false, "pre_selected": false, "needs": { "code": "BUNDLE_INCOMPLETE", "message": "Add the remaining items to complete this combo", "missing": [ { "component": 0, "required": 1, "available": 0 }, { "component": 1, "required": 1, "available": 0 }, { "component": 2, "required": 1, "available": 0 } ] } } ] } ``` #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | An unknown parameter | | 401 | `UNAUTHORIZED` | Missing or unknown POS key, or one the loyalty program no longer accepts | | 413 | `PAYLOAD_TOO_LARGE` | The body is over 256 KB | | 429 | `RATE_LIMITED` | Too many requests for this key. See `Retry-After` | | 503 | `OFFERS_UNAVAILABLE` | Promotions or policy could not be read | | 503 | `CUSTOMER_LOOKUP_UNAVAILABLE` | The `customer` token could not be resolved | ### POS Quick Pay pass-through Pay with a customer's app balance from the POS. These routes forward to Spoonity's loyalty platform and return its HTTP status and body unchanged. Offers implements no Quick Pay rules: no sign check, no balance check, no idempotency and no error mapping. Nothing is written to Offers' database. **Auth:** `Authorization: Bearer` POS key (or `X-Spoonity-POS-Key`). The key is the store's Spoonity API key and is passed on to the loyalty platform; a key that is not one answers `401 UNAUTHORIZED`. Same rate limit, body limit and `X-Spoonity-Api-Version` header as the other POS routes. ### POST /partners/pos/quickpay/order Forwarded as `POST /order`. Redeem (negative `amount`) or load (positive). #### Request body | Field | Type | Required | Description | |---|---|---|---| | `card_number` | string | Yes | The scanned code, prefix included. Offers removes the merchant's code prefix | | `amount` | integer | Yes | Signed cents: positive loads, negative redeems. Sent on as decimal dollars (`-1250` becomes `-12.5`) | | `till` | integer | | Required by the loyalty platform | | `receipt_number` | string | | Required by the loyalty platform. Unique per attempt | | `cashier` | object | | `{ id, name }` | Any other field is passed on unchanged. Offers rejects only an `amount` that is not an integer and a `card_number` that is not a non-empty string (`400`). #### Example request ```bash curl -X POST https://offers.spoonity.com/partners/pos/quickpay/order \ -H "Authorization: Bearer YOUR_POS_KEY" \ -H "Content-Type: application/json" \ -d '{ "card_number": "SPN123456789", "amount": -1250, "till": 2, "receipt_number": "S12-1042-1", "cashier": { "id": 17, "name": "Dana" } }' ``` #### Example response The loyalty platform's reply. A refusal is HTTP 200 with `success: false` and the cause in `error.errors[]`. Balances are in dollars. ```json { "success": true, "reference_number": "303188170", "receipt_data": { "lines": ["Successfully redeemed 12.50 quick pay balance"], "outstanding": 0, "user": { "id": "22293026", "card_number": "123456789", "balances": [{ "id": 9559, "currency": "Canadian Dollar", "balance": 37.5, "type": "Quick Pay" }] } }, "error": { "errors": [], "code": null, "reference_id": null } } ``` #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | `amount` is not an integer, or `card_number` is missing or empty | | 401 | `UNAUTHORIZED` | Missing or unknown POS key, or a key that is not a Spoonity API key | | 503 | `QUICKPAY_UNAVAILABLE` | The loyalty platform did not answer within 8 seconds, or could not be reached | Every other status and body is the loyalty platform's. ### GET /partners/pos/quickpay/balance Forwarded as `GET /quick-pay`. Query: `card_number` (required, prefix included). Same reply shape as `order`; `receipt_data.user.balances[]` holds the balance in dollars. ```bash curl "https://offers.spoonity.com/partners/pos/quickpay/balance?card_number=SPN123456789" \ -H "Authorization: Bearer YOUR_POS_KEY" ``` ### POST /partners/pos/quickpay/void Forwarded as `POST /order/void`, body unchanged. Send the `reference_number` of a load's reply as `receipt`, as a number. The loyalty platform voids only the customer's most recent Quick Pay receipt and does not void a redemption; reverse a redemption by loading the same amount back. ```bash curl -X POST https://offers.spoonity.com/partners/pos/quickpay/void \ -H "Authorization: Bearer YOUR_POS_KEY" \ -H "Content-Type: application/json" \ -d '{ "receipt": 303188169 }' ``` A successful reply is `{ "voided": true }`. ## App reward picks API For a merchant's mobile app. The customer picks a reward in the app before the till; when the cashier scans their code, the POS check applies it. See the [app reward picks guide](app.md) for the flow. **Base path:** `https://offers.spoonity.com/partners/app` **Auth:** `Authorization: Bearer` customer session key and `X-Spoonity-Vendor`, see [Customer session](#customer-session-partnersapp). ### POST /partners/app/selections Pick a reward for today. #### Request body | Field | Type | Required | Description | |---|---|---|---| | `reward_id` | integer | One of the two | The loyalty reward id (`vendor_perk_redemption_id`). Maps to offer `off_r` | | `offer_id` | string | One of the two | The offer id | Send exactly one. Unknown fields are a `400`. #### Example request ```bash curl -X POST https://offers.spoonity.com/partners/app/selections \ -H "Authorization: Bearer CUSTOMER_SESSION_KEY" \ -H "X-Spoonity-Vendor: 2112901" \ -H "Content-Type: application/json" \ -d '{ "reward_id": 501 }' ``` #### Example response `201` for a new pick, `200` when the reward was already picked today. ```json { "selection": { "selection_id": "sel_8d0c6f5e-4b7a-4a51-9a59-0d1f8f0c1e2a", "offer_id": "off_r501", "reward_id": 501, "name": "Free Fries", "business_date": "2026-10-15", "expires_at": "2026-10-16T08:00:00.000Z", "state": "open" } } ``` #### Errors | Status | Code | When | |---|---|---| | 400 | `INVALID_REQUEST` | Validation failed, including both or neither of `reward_id` and `offer_id` | | 401 | `UNAUTHORIZED` | Header missing, session invalid, vendor not set up, or no loyalty account | | 409 | `OFFER_NOT_AVAILABLE` | The customer cannot have the reward now. `error.reason` is `{ code, message }`, a code from [Reason codes](#reason-codes) or `OFFER_NOT_FOUND` | | 409 | `TOO_MANY_SELECTIONS` | 10 open picks today already | | 413 | `PAYLOAD_TOO_LARGE` | The body is over 256 KB | | 429 | `RATE_LIMITED` | Too many requests. See `Retry-After` | | 503 | `LOYALTY_UNAVAILABLE` | The merchant's loyalty host could not be reached | ### GET /partners/app/selections Today's picks that can still apply, oldest first, as `{ "selections": [...] }` with the same fields as above. `state` is `open` (waiting for the till) or `pending` (a POS check holds it until the check closes, at most 15 minutes). Used, cancelled and expired picks are not listed. #### Errors | Status | Code | When | |---|---|---| | 401 | `UNAUTHORIZED` | Header missing, session invalid, vendor not set up, or no loyalty account | | 429 | `RATE_LIMITED` | Too many requests. See `Retry-After` | | 503 | `LOYALTY_UNAVAILABLE` | The merchant's loyalty host could not be reached | ### DELETE /partners/app/selections/{selection_id} Take a pick back. Answers `{ "cancelled": true }`, and the same again when repeated. #### Errors | Status | Code | When | |---|---|---| | 401 | `UNAUTHORIZED` | Header missing, session invalid, vendor not set up, or no loyalty account | | 404 | `NOT_FOUND` | No such pick for this customer | | 409 | `SELECTION_USED` | The check that applied it has closed | | 429 | `RATE_LIMITED` | Too many requests. See `Retry-After` | | 503 | `LOYALTY_UNAVAILABLE` | The merchant's loyalty host could not be reached | ## Reason codes `reason.code` on an offer result (`needs.code` on the POS cashier prompt). The status column is where the code is normally seen. Extra fields are machine-readable context next to `code` and `message`. | Code | Status | Meaning | Extra fields | |---|---|---|---| | `MIN_SPEND_NOT_MET` | inapplicable | Subtotal below `min_spend` | `shortfall` (cents); `basis: "eligible"` when the policy uses the eligible subtotal | | `NO_ELIGIBLE_ITEMS` | applicable | A free item offer whose SKU is not in the cart. The offer also carries `add_item_hint: { sku }` | | | `OUTSIDE_ACTIVE_WINDOW` | inapplicable | Before `active.start` or after `active.end` | | | `OUTSIDE_DAYPART` | inapplicable | Outside every daypart | | | `TIER_NOT_ELIGIBLE` | inapplicable | The customer's loyalty tier is not in `tiers` | | | `INSUFFICIENT_BALANCE` | inapplicable | Not enough points for a point-cost reward (a guest has 0) | `required`, `balance` | | `CODE_REQUIRED` | inapplicable | Simulate `explain` only: a code-gated offer whose code was not entered. Evaluate leaves such offers out | | | `CONDITION_NOT_MET` | inapplicable | Another condition failed (segment, tag, first order, order count, store, channel condition) | `attribute` | | `STORE_NOT_ELIGIBLE` | inapplicable | `store_id` not in `stores` | | | `CHANNEL_NOT_ELIGIBLE` | inapplicable | `channel` not in `channels` | | | `EXCLUSIVE_CONFLICT` | skipped | An exclusive offer applied, or this exclusive offer could not apply alongside those already applied | | | `LOWER_VALUE_THAN_APPLIED` | | Reserved. Not emitted today | | | `UNIT_CONFLICT` | skipped | The units it needs already carry another offer's discount | | | `MAX_OFFERS_REACHED` | skipped | The policy's `max_applied_offers` was reached | | | `ZERO_DISCOUNT` | skipped | It would not reduce the total (for example, the order is already fully discounted) | | | `ALREADY_USED` | inapplicable | A single-use offer this customer already redeemed | | | `RESERVED` | inapplicable | A single-use offer held by another order in progress | | | `CUSTOMER_REQUIRED` | inapplicable | The offer needs an identified customer | `because: "single_use"` when implied by single use or a per-customer cap | | `USAGE_LIMIT_REACHED` | inapplicable | A usage limit was reached | `scope` (`total`, `per_customer`, `per_day`), `limit`, `used` | | `BUDGET_EXHAUSTED` | inapplicable | `budget_cents` is spent | `budget_cents`, `spent_cents` | | `GROUP_CONFLICT` | skipped | Another offer in the same `stacking.group` applied | `group`, `applied_offer_id` | | `LOCALLY_DISCOUNTED` | skipped | The units it needs carry a POS line discount and the policy is `respect`. Check-level POS discounts never cause it | | | `ORDER_CAP_REACHED` | skipped | Trimmed to nothing by `max_order_discount_percent` | `cap` | | `MIN_QUANTITY_NOT_MET` | inapplicable | Fewer eligible units than `min_quantity` | `required`, `eligible` | | `TIER_NOT_REACHED` | inapplicable | No spend tier reached | `next_min_spend`, `shortfall` | | `BUNDLE_INCOMPLETE` | applicable | The cart does not hold a complete combo set | `missing: [{ component, required, available }]` | ## Rate limits The partner routes (`/partners/pos/*` and `/partners/app/*`) are rate limited per credential. The default is 20 requests per second sustained, with bursts of up to 60. A credential that is over the limit gets: ``` HTTP/1.1 429 Too Many Requests Retry-After: 1 ``` ```json { "error": { "code": "RATE_LIMITED", "message": "Too many requests; retry after the Retry-After interval", "retry_after_seconds": 1 } } ``` Wait `Retry-After` seconds, then retry. A POS that is still limited after that closes the check without a discount. The limit is counted in each running instance of the service, so the ceiling across the service is a little higher than the figure above. It protects against a runaway client; it is not a quota. Every route also refuses a request body over 256 KB with `413 PAYLOAD_TOO_LARGE`. ## Error codes Every error on this service, by code. Each endpoint above lists the ones it returns. | Status | Code | Meaning | |---|---|---| | 400 | `INVALID_REQUEST` | Validation failed. `issues[]` lists `{ path, message }` | | 400 | `UNKNOWN_LINES` | Partial return named lines that are not in the redemption | | 401 | `UNAUTHORIZED` | Missing or invalid credential | | 403 | `FORBIDDEN` | Read-only role attempted a write | | 404 | `NOT_FOUND` | Unknown route, or a resource that does not exist for this vendor | | 409 | `OFFERS_RESERVED` | A single-use offer is held by another order | | 409 | `EVALUATION_TERMINAL` | The `evaluation_id` is already finished | | 409 | `VERSION_REQUIRED` | An update without `expected_version` | | 409 | `VERSION_CONFLICT` | An update with a stale `expected_version` | | 409 | `PROMOTION_ARCHIVED` | An edit to an archived promotion | | 409 | `PROMOTION_EXISTS` | Create with an identifier that is taken | | 409 | `INVALID_STATE` | A redemption in the wrong state for the action | | 409 | `CHECK_CLOSED` | POS: the check already closed | | 409 | `CHECK_REOPEN_LIMIT` | POS: the check has no evaluation ids left | | 409 | `OFFER_NOT_AVAILABLE` | App: the customer cannot have the reward now. `error.reason` says why | | 409 | `TOO_MANY_SELECTIONS` | App: 10 open picks today already | | 409 | `SELECTION_USED` | App: the pick was used by a check that closed | | 409 | `NOT_RETRYABLE` | Loyalty outbox: only a `dead` row can be retried | | 413 | `PAYLOAD_TOO_LARGE` | The request body is over 256 KB. Any route | | 429 | `RATE_LIMITED` | Too many requests for this key. `Retry-After` gives the seconds to wait. POS and app routes | | 500 | `INTERNAL` | Unexpected server error | | 503 | `OFFERS_UNAVAILABLE` | Catalog, policy, loyalty source or database unavailable. Retryable | | 503 | `CUSTOMER_LOOKUP_UNAVAILABLE` | POS: a customer QR token could not be resolved. Retryable | | 503 | `LOYALTY_UNAVAILABLE` | App: the merchant's loyalty host could not be reached. Retryable | | 503 | `QUICKPAY_UNAVAILABLE` | POS Quick Pay: the loyalty platform could not be reached or took over 8 seconds | ## Health ### GET /readyz Readiness. No credential. #### Example request ```bash curl https://offers.spoonity.com/readyz ``` #### Example response ```json { "ready": true, "db": "ok" } ``` `503 { "ready": false, "db": "connecting" }` (or `"unavailable"`) while the database is not answering. `GET /healthz` exists in the service but is not usable on `offers.spoonity.com`: the hosting frontend answers that path itself with a 404. Use `/readyz`. ## Not on this page - **Partner protocol layers.** The service also has translators for specific partner promotion protocols (Olo, Toast, NCR PES, the Deliverect loyalty partner and Deliverect Commerce). They are not enabled on `offers.spoonity.com` today. Some of their routes appear in the [OpenAPI spec](https://prism.spoonity.com/docs/openapi/offers.yaml) because the spec is shared with the service repository. - **Tax, offline mode and points accrual.** The engine is pre-tax, needs a live connection, and does not post points; the loyalty platform does. ## See also - [Overview](index.md) · [Kiosk and ordering app guide](kiosk.md) · [POS check guide](pos.md) - [Authentication](https://prism.spoonity.com/docs/authentication) · [Conventions](https://prism.spoonity.com/docs/conventions) - [OpenAPI spec](https://prism.spoonity.com/docs/openapi/offers.yaml)