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 (
1149is $11.49). A decimal is a400. The one exception isorder_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: 3is 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),inapplicableorskipped, with a stablereason.codeand areason.messageyou can show a guest or cashier. - Fail open.
503 OFFERS_UNAVAILABLEmeans 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.
- Your POS sends the whole check when the cashier presses pay: read the POS check guide.
- You build a merchant's mobile app and want the customer to pick a reward before the till: read the app reward picks guide.
- You need every field, route and error code: read the API reference.
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/jsonon every request with a body. - Every response carries
X-Request-Id. Send your ownX-Request-Idto have it echoed and logged, and quote it when you report a problem. - Every error has the same shape:
{ "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: an index of every page with a one-line summary./docs/llms-full.txt: every page in one file./docs/<page>.md: any single page as markdown, for example/docs/pos.mdor/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.