# App reward picks (`/partners/app`)

This guide is for developers of a merchant's mobile app. It lets a customer
pick a loyalty reward in the app before they reach the till. When the
cashier scans the customer's code, the POS check finds the pick and applies
it. The POS never sees a list of rewards.

**Base URL:** `https://offers.spoonity.com`, or the host the merchant's POS
integration uses. Path prefix: `/partners/app`.

## 1. The flow

1. The customer opens the app and picks a reward: `POST /partners/app/selections`,
   with the code the app is showing.
2. The app shows the pick as ready at the till, and sends its new code to
   `PUT /partners/app/code` every time the code changes.
3. The cashier scans the customer's code. The POS sends it on its `check`
   call (see the [POS check guide](pos.md)).
4. Spoonity finds the customer's picks for today and applies them to the
   check. The pick is held while the check is open and used when it closes.

The app takes no part in steps 3 and 4. It can list the picks again to show
that one is at the till.

## 2. Authentication

Every request sends two headers:

```
Authorization: Bearer <session_key>
X-Spoonity-Vendor: <vendor_id>
```

- `session_key` is the customer's Spoonity loyalty session, the same one the
  app already uses for the native API. It is never an API key. Do not put an
  API key in an app.
- `X-Spoonity-Vendor` is the merchant's Spoonity vendor id.
- Spoonity validates the session on the merchant's loyalty host and keeps a
  valid session for 5 minutes. A sign-out is therefore seen within 5
  minutes.
- The session decides who the customer is. The body never names a customer
  or a vendor.
- `Content-Type: application/json` on requests with a body. Unknown fields
  are a `400`.

## 3. POST /partners/app/selections

Pick a reward for today. Send exactly one of `reward_id` or `offer_id`:

```json
{ "reward_id": 501 }
```

```json
{ "offer_id": "off_r501" }
```

`reward_id` is the loyalty reward id the app already lists
(`vendor_perk_redemption_id`). It maps to the offer `off_r<reward_id>`.

Send the code the app is showing with the pick, so the till recognises the
customer:

```json
{ "reward_id": 501, "code": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "customer_identifier": "ada@example.com" }
```

| Field | Type | Meaning |
|---|---|---|
| `code` | string, 1 to 512, optional | The scannable code the app is showing right now, exactly as the cashier will scan it. When the merchant's POS recognises codes by a prefix, it may be sent with or without it: Spoonity stores it without the prefix, as the till looks it up. |
| `customer_identifier` | string, 1 to 256, optional | The merchant's default customer identifier (for example the loyalty token, email or phone). Spoonity names the customer by it when it posts the sale to the loyalty program. Used together with `code`. |

Response `201` for a new pick, or `200` when this reward was already picked
today (the same pick is returned):

```json
{
  "selection": {
    "selection_id": "sel_8d0c6f5e-4b7a-4a51-9a59-0d1f8f0c1e2a",
    "offer_id": "off_r501",
    "reward_id": 501,
    "name": "Free Fries",
    "business_date": "2026-10-15",
    "expires_at": "2026-10-16T08:00:00.000Z",
    "state": "open"
  }
}
```

Spoonity checks once, at pick time, that this customer can have the reward
now: points, tier, segment, active dates, and whether it was already used.
It does not check the cart (minimum spend, items), the store or the time of
day. Those are judged at the till.

How many picks apply on one check is decided at the till by the merchant's
promotion policy, not here.

## 4. GET /partners/app/selections

Today's picks that can still apply, oldest first.

```json
{
  "selections": [
    { "selection_id": "sel_8d0c6f5e-4b7a-4a51-9a59-0d1f8f0c1e2a", "offer_id": "off_r501", "reward_id": 501,
      "name": "Free Fries", "business_date": "2026-10-15", "expires_at": "2026-10-16T08:00:00.000Z",
      "state": "pending" }
  ]
}
```

| `state` | Meaning |
|---|---|
| `open` | Picked, waiting for the till. |
| `pending` | A POS check has applied it and holds it until the check closes (at most 15 minutes). Show it as "at the till". |

Used, cancelled and expired picks are not listed.

## 5. DELETE /partners/app/selections/:selection_id

Take a pick back. Response `200`:

```json
{ "cancelled": true }
```

- Repeating it gives the same answer.
- A `pending` pick can be cancelled. The check already at the till keeps its
  discount on screen; the pick is just not applied to the next check.
- A pick that belongs to another customer or another merchant answers `404`.
- A pick whose check has closed answers `409 SELECTION_USED`.

## 6. PUT /partners/app/code

Tell Spoonity the code the app is showing now. Call it every time the code
changes while the customer has an open pick today (loyalty codes rotate
every few minutes).

```json
{ "code": "ffeeddccbbaa99887766554433221100", "customer_identifier": "ada@example.com" }
```

Response `204` with no body. The fields are those of `POST
/partners/app/selections`; `code` is required.

- A code is valid until the end of the merchant's business day.
- Spoonity keeps the 20 most recent codes per customer per business day.
- A code sent again by another customer now belongs to that customer.
- Spoonity stores only a hash of the code.

## 7. Business day

A pick is valid until the end of the merchant's business day. The day starts
at a local cutoff in the merchant's time zone, so a pick made at 01:30 on
Saturday, with a 04:00 cutoff, belongs to Friday's business day and expires at
04:00 on Saturday.

- `expires_at` is the end of the business day in UTC. Use it to show and to
  hide a stale pick.
- `business_date` is the local date the business day is named after.
- Do not work out the business day on the device. Around daylight saving
  changes a business day is 23 or 25 hours long.

## 8. How a pick reaches the POS check

1. The POS sends the scanned code as `customer.customer_id` on
   `POST /partners/pos/check`.
2. Spoonity resolves the code to the customer and loads that customer's
   `open` and `pending` picks for today at that merchant.
3. The picks join the check's selected offers. A pick that applies becomes
   `pending`, linked to that check.
4. When the check closes, the pick is `used`. If the check is voided while
   open, its hold lapses, or a later `check` for it no longer applies the
   pick, the pick goes back to `open`.

```
          pick                check applies it              close
 (none) ------> open ---------------------------> pending ---------> used
                 ^  \                                 |
                 |   \ DELETE                         | void while open, hold expired,
                 |    v                               | or re-check without it
                 |  cancelled                         |
                 +------------------------------------+
   open or pending past expires_at: expired (not listed, not applied)
```

A pick never applies to another merchant's check.

When the merchant is set up for app picks, Spoonity recognises the customer
from the codes the app sent, without asking the loyalty platform at the
till. A code the app never sent prices the check as a guest, so send the
code with every pick and every time it changes.

## 9. Errors

Error bodies are `{ "error": { "code": "...", "message": "..." } }`.

| Status | `code` | When | App action |
|---|---|---|---|
| 400 | `INVALID_REQUEST` | The body failed validation (`issues[]` says where), for example both `reward_id` and `offer_id`, or neither. | Fix the request. |
| 401 | `UNAUTHORIZED` | A header is missing, the session is invalid or expired, the merchant is not set up for picks, or the session has no loyalty account at this merchant. | Sign the customer in again. |
| 404 | `NOT_FOUND` | No such pick for this customer. | Refresh the list. |
| 409 | `OFFER_NOT_AVAILABLE` | The customer cannot have the reward now. `error.reason.code` says why and `error.reason.message` can be shown. | Show the message. |
| 409 | `TOO_MANY_SELECTIONS` | The customer already has 10 open picks today. | Ask them to cancel one first. |
| 409 | `SELECTION_USED` | The check that applied the pick has closed. | Refresh the list. |
| 413 | `PAYLOAD_TOO_LARGE` | The body is over 256 KB. | Fix the request. |
| 429 | `RATE_LIMITED` | Too many requests. The `Retry-After` header gives the seconds to wait. | Wait, then retry. |
| 500 | `INTERNAL` | An error on Spoonity's side. | Retry later. |
| 503 | `LOYALTY_UNAVAILABLE` | The merchant's loyalty host could not be reached. | Retry later. |
| 503 | `UNAVAILABLE` | Spoonity's database is temporarily unavailable. | Retry later. |

`error.reason.code` on `OFFER_NOT_AVAILABLE` is one of `OFFER_NOT_FOUND`,
`INSUFFICIENT_BALANCE`, `TIER_NOT_ELIGIBLE`, `CONDITION_NOT_MET`,
`ALREADY_USED`, `RESERVED`, `USAGE_LIMIT_REACHED`, `OUTSIDE_ACTIVE_WINDOW`,
`CHANNEL_NOT_ELIGIBLE`, `CODE_REQUIRED` and `BUDGET_EXHAUSTED`. See the
[reason codes](reference.md#reason-codes) in the reference.

## 10. Limits

- 10 open picks per customer per business day. Two picks sent at the same
  moment can both succeed, so the count can reach 11 in that race.
- Requests are rate limited per credential. See the
  [rate limit](reference.md#rate-limits) section of the reference.
