# 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/<page>.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.
