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
- The customer opens the app and picks a reward:
POST /partners/app/selections, with the code the app is showing. - The app shows the pick as ready at the till, and sends its new code to
PUT /partners/app/codeevery time the code changes. - The cashier scans the customer's code. The POS sends it on its
checkcall (see the POS check guide). - 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_keyis 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-Vendoris 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/jsonon requests with a body. Unknown fields are a400.
3. POST /partners/app/selections
Pick a reward for today. Send exactly one of reward_id or offer_id:
{ "reward_id": 501 }
{ "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:
{ "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):
{
"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.
{
"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:
{ "cancelled": true }
- Repeating it gives the same answer.
- A
pendingpick 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).
{ "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_atis the end of the business day in UTC. Use it to show and to hide a stale pick.business_dateis 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
- The POS sends the scanned code as
customer.customer_idonPOST /partners/pos/check. - Spoonity resolves the code to the customer and loads that customer's
openandpendingpicks for today at that merchant. - The picks join the check's selected offers. A pick that applies becomes
pending, linked to that check. - When the check closes, the pick is
used. If the check is voided while open, its hold lapses, or a latercheckfor it no longer applies the pick, the pick goes back toopen.
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 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 section of the reference.