Spoonity OffersView as markdown

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.

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": [] } }
CodeStatusWhat to do
UNAUTHORIZED401Missing or wrong key, or a key sent as ?api_key=. A configuration problem; do not retry.
INVALID_REQUEST400Malformed 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_RESERVED409Only 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_TERMINAL409This evaluation_id already has a committed, cancelled or expired redemption. Start again with a new id.
OFFERS_UNAVAILABLE503Offers could not read what it needs. Take payment without discounts. Do not block the sale.
UNKNOWN_LINES400On /returns: some line_ids are not part of that redemption.
INVALID_STATE409On /returns: the redemption is not committed.
NOT_FOUND404Management routes: unknown id, or a record that belongs to another merchant.
INTERNAL500A 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