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. If your POS sends the whole check at pay time instead of building a cart itself, read the POS check guide.
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: <key>, or Authorization: Bearer <key>. 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.
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
{
"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.
{
"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.
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'sreceipt_numberin step 6. Do not create a new one per cart edit. It is 1 to 128 characters fromA-Z a-z 0-9 _ . : -.add_item_hint. A free-item offer whose item is not in the cart yet comes backstatus: "applicable"withadd_item_hint: { sku }instead of a discount. Show it as a prompt ("Add a cookie to use this reward").
First call, nothing selected yet:
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 }
]
}
}
{
"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:
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.
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 }
}
{
"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.
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 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:
{ "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
statusandreasonalready reflect that. - Tax on discounts. Every total here is pre-tax. Apply tax as you
already do, on
order_payload.total.