# 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: <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](#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`.
