Spoonity OffersView as markdown

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).
  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>

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" }
FieldTypeMeaning
codestring, 1 to 512, optionalThe 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_identifierstring, 1 to 256, optionalThe 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" }
  ]
}
stateMeaning
openPicked, waiting for the till.
pendingA 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 }

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.

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.

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": "..." } }.

StatuscodeWhenApp action
400INVALID_REQUESTThe body failed validation (issues[] says where), for example both reward_id and offer_id, or neither.Fix the request.
401UNAUTHORIZEDA 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.
404NOT_FOUNDNo such pick for this customer.Refresh the list.
409OFFER_NOT_AVAILABLEThe customer cannot have the reward now. error.reason.code says why and error.reason.message can be shown.Show the message.
409TOO_MANY_SELECTIONSThe customer already has 10 open picks today.Ask them to cancel one first.
409SELECTION_USEDThe check that applied the pick has closed.Refresh the list.
413PAYLOAD_TOO_LARGEThe body is over 256 KB.Fix the request.
429RATE_LIMITEDToo many requests. The Retry-After header gives the seconds to wait.Wait, then retry.
500INTERNALAn error on Spoonity's side.Retry later.
503LOYALTY_UNAVAILABLEThe merchant's loyalty host could not be reached.Retry later.
503UNAVAILABLESpoonity'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