Spoonity Offers API
Spoonity Offers is the 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. The caller displays what it is given and submits it as-is. It never computes a discount itself.
Two kinds of offer are evaluated 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. They live in the engine's own catalog and are managed with the admin catalog API below (Prism's Promotions section uses the same API).
- Loyalty rewards: point-cost rewards defined in the Spoonity loyalty program. The engine reads them from the loyalty platform; they are read-only here.
Base URL: https://offers.spoonity.com
Machine-readable spec: openapi/offers.yaml (OpenAPI 3.1).
How the engine decides
The same input always produces the same output. These rules hold on every surface on this page.
- Integer cents. Every amount in a request and a response is an integer
number of cents (
1149is $11.49). A decimal is a400. The one exception isorder_payloadin the evaluate response, which is in decimal dollars because it is built for the loyalty platform's order endpoint. - Pre-tax. Every subtotal, discount and total is before tax. Tax is applied downstream by the POS or loyalty platform.
- Deterministic. The engine takes the clock as an input and never reads it mid-evaluation. Ties are broken by explicit rules (price, then cart position, then offer id), not by iteration order.
- One discount per unit. A cart line with
quantity: 3is three units. Each unit can carry at most one item-level discount. Item-level offers are applied first; order-level offers then apply to what is left. - Allocation that adds up. An order-level discount is spread across the
lines with a largest-remainder method, so the per-line
allocationsalways sum to the discount. - Stacking. Arbitration order is: offers the guest selected or unlocked
with a code, then higher
stacking.priority, then the higher standalone value for this cart, then offer id. Three controls limit combination:stacking.exclusive: true: once an exclusive offer applies, every other requested offer is skipped withEXCLUSIVE_CONFLICT.stacking.group: one applied offer per group; the rest are skipped withGROUP_CONFLICT.- The vendor's promotion policy: a cap on applied
offers (
MAX_OFFERS_REACHED), a cap on the order discount as a percent (ORDER_CAP_REACHED), and whether order-level percentages cascade or add.
- Reason codes. Every offer in a response has exactly one status:
applied,applicable(would apply if selected),inapplicable(failed an eligibility check) orskipped(lost arbitration). An offer that did not apply carriesreason: { code, message, ... }.codeis stable and machine-readable;messageis display text for a guest or cashier. See Reason codes. - Discounts the POS already applied. A line may carry
discountsthe register applied itself (employee, manager, senior). Order-level discounts are always computed on the total after them, and by default the engine does not add an item-level discount to such a line (LOCALLY_DISCOUNTED).
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 | Vendor API key |
| Admin catalog | /v1/admin/* | A merchant's back office, or Prism | Vendor API key, or OIDC service identity |
| 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 a customer can pick a reward before the till | Customer session key (Authorization: Bearer) plus X-Spoonity-Vendor |
| Health | /readyz | Monitoring | None |
Authentication
Offers accepts four credentials. Which one applies depends on the path. Authentication covers them alongside the other services.
Vendor API key (/v1/*)
Send the key in either header:
X-API-Key: YOUR_OFFERS_API_KEY
Authorization: Bearer YOUR_OFFERS_API_KEY
X-API-Key is checked first. The key determines the vendor; no request
carries a vendor id. Keys are issued by Spoonity. There is no self-service
key page for Offers in Prism.
The key must be in a header. On offers.spoonity.com a request with
?api_key= in the URL is refused with 401 UNAUTHORIZED even when the key
is correct, because URLs are written to request logs.
An API key has no role, so it can call every /v1/* route, including admin
writes.
POS key (/partners/pos/*)
Authorization: Bearer YOUR_POS_KEY
X-Spoonity-POS-Key: YOUR_POS_KEY is also accepted. The key alone
determines the merchant and the store; no vendor or store id is ever read
from the body or query (there is no store_id field).
Two kinds of key work:
- A key Spoonity issued for the merchant. The merchant is also the store.
- A store's own Spoonity API key (a store vendor under the merchant). The first request with a key Spoonity has not seen is checked once with the loyalty program; when the key belongs to a store of a merchant connected to Offers, it is remembered and accepted from then on. The request runs for the merchant (promotions, app picks, codes and settings are the merchant's), the store is the key's store, and the store's closed checks are posted to the loyalty program with the store's own key.
A missing or unknown key, a store key of another merchant, and a key the
loyalty program no longer accepts (deactivated, expired or deleted) are
401 UNAUTHORIZED. A key the loyalty program rejects on any call is revoked
and stays refused: replace it in the POS configuration. When a new key
cannot be checked because the loyalty program is down, the answer is
503 OFFERS_UNAVAILABLE and nothing is remembered. The /v1 credentials
are not accepted on /partners/pos, and a POS key is not accepted on /v1.
Customer session (/partners/app/*)
Authorization: Bearer CUSTOMER_SESSION_KEY
X-Spoonity-Vendor: 2112901
The customer's Spoonity loyalty session, never an API key. The session is
validated on the merchant's loyalty host and a valid session is cached for 5
minutes. The session decides the customer; the body never does. A missing
header, an invalid session or an unknown vendor is 401 UNAUTHORIZED.
App reward picks has the endpoints.
OIDC service identity (trusted Spoonity services)
Trusted Spoonity services such as Prism's BFF call /v1/* with a
Google-signed ID token instead of a key. This path is not available to
external integrators; it is listed so the headers you see Prism send make
sense.
| Header | Required | Meaning |
|---|---|---|
Authorization: Bearer <Google ID token> | Yes | Token for an allow-listed service account, with this service as the audience |
X-Spoonity-Vendor | Yes, ^[A-Za-z0-9_-]{1,64}$ | The vendor the call acts for. Missing or malformed is 401 |
X-Spoonity-User | No, 1 to 256 printable characters | The person acting; stamped on created_by / updated_by |
X-Spoonity-Role | No | Exactly admin, editor or viewer. Absent, or any other value, is treated as viewer |
A viewer gets 403 FORBIDDEN on every non-GET /v1/admin/* route except
POST /v1/admin/promotions/simulate, which has no side effects.
Conventions
Errors use one envelope everywhere on this service:
{ "error": { "code": "INVALID_REQUEST", "message": "Promotion validation failed", "issues": [ { "path": "discount_amount", "message": "percent discounts must be between 0 and 100" } ] } }codeis the stable part.issues[]appears on validation errors, one entry per field. Some codes add fields (version,conflict_offer_ids,state); each endpoint lists them. This differs from CMS and Links, whoseerroris a string; see Conventions.Unknown fields. Admin and POS request bodies reject unknown fields with
400, so a typo cannot silently change a promotion. On/partners/pos, fields of your own go inmetadata, which is accepted and ignored.POST /v1/evaluateignores fields it does not know.Limits. 200 lines per cart, 1 to 1000 units per line, 2000 units per cart, amounts 0 to 100,000,000 cents, at most 50 entries in
codes,selected,categoriesandmodifiers. Over any limit is a400.Identifiers.
evaluation_id, promotionidentifier,requires_codeandstacking.groupare 1 to 128 characters fromA-Z a-z 0-9 _ . : -. SKUs, category ids and other ids you own are 1 to 128 characters of anything.Timestamps. Promotion, policy and redemption records use epoch milliseconds (
created_at,updated_at,committed_at). Lock and hold expiries are ISO 8601 strings. Usage days areYYYY-MM-DDUTC dates.Versioning. The version is in the path (
/v1). The POS check API (/partners/pos) answers withX-Spoonity-Api-Version: 2026-10-16; see POS check API.Request ids. Every response carries
X-Request-Id. Send your ownX-Request-Idto have it echoed and logged; quote it when reporting a problem.Fail open. A
503 OFFERS_UNAVAILABLEmeans the engine could not read what it needs (catalog, policy, database). It is retryable. A checkout that receives it should proceed at full price rather than block the guest.
Evaluate and lifecycle
A device that builds its own cart uses this surface. The loop:
- Evaluate on every change. Call
POST /v1/evaluatewhenever the cart or the guest's selection changes. Reuse oneevaluation_idfor the whole checkout attempt; each call replaces the previous result for that id. Always send the full current cart and selection. - Lock before payment. Call it once more with
lock: { ttl_seconds }. This reserves single-use offers so a concurrent order cannot take them, and records apendingredemption. The response carriesredemption_idandlock. - Submit the order. Send
order_payloadto the loyalty platform unchanged. Itsreceipt_numberis theevaluation_id. - Commit is event-driven. When the order lands, an
order.submittedevent posted to/webhooks/eventsturns the pending redemption intocommitted. A device never calls a commit endpoint. A pending redemption that is never committed expires when its hold lapses, and an expired one does not count against single-use offers or usage limits. - Undo when needed. Release an abandoned lock with
DELETE /v1/locks/{key}, or roll back, cancel or partially return a redemption with the/v1/redemptions/{id}routes.
Redemption states:
pending --commit--> committed --return--> partially_returned
| | |
| +--------rollback--------+--> rolled_back
+--cancel / void--> cancelled
+--hold lapses----> expired
rolled_back, cancelled and expired are terminal. A commit that arrives
after the hold expired is refused and the record expires, so a lapsed hold
can never commit. Usage limits and budgets are computed from committed
records, so a rollback restores both the use and the budget. A partial return
restores neither.
POST /v1/evaluate
Price a cart against the vendor's promotions and loyalty rewards.
Auth: Vendor API key, or OIDC service identity.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
evaluation_id | string | Yes | Your id for this checkout attempt. Reuse it on every call for the attempt. Becomes order_payload.receipt_number |
cart.line_items[] | array | Yes | 1 to 200 lines, see below |
customer.identifier | string | Loyalty customer identifier. Resolves tier, segments, balances and pre-selected rewards when the vendor's loyalty program is connected to Offers; otherwise the cart is priced for a guest | |
customer.pos_session_hash | string | Alternative identifier from a POS session | |
customer.order_count | integer | Orders the customer has placed, if you know it. A value the loyalty platform resolves wins | |
customer.tags | string[] | Customer tags, if you know them. A resolved list wins | |
codes | string[] | Promo codes the guest entered | |
selected | string[] | Offer ids the guest chose (typically point-cost rewards) | |
selection_mode | string | manual (default): only selected, code-unlocked and auto-apply offers apply. automatic: every eligible offer is treated as requested. list: nothing applies; eligible offers come back applicable, for a picker UI | |
store_id | string | Store, for store-restricted offers | |
channel | string | Channel, for example kiosk, web, pos | |
lock.ttl_seconds | integer | 1 to 3600. Marks this as the final evaluate before payment: reserves single-use offers and records a pending redemption |
A line is { line_id, id, name?, categories?, price, quantity, modifiers?, discounts? }:
| Field | Type | Description |
|---|---|---|
line_id | string | Unique within the cart |
id | string | Your SKU or PLU. Promotions target it through products |
categories[] | { id, name? } | Promotions target these through categories |
price | integer cents | Unit price excluding modifiers |
quantity | integer | 1 to 1000 |
modifiers[] | { id, name?, price, quantity } | Unit price and quantity per modifier |
discounts[] | { id, name?, amount, source? } | Discounts the POS already applied to the whole line, cents. At most 10. source is pos (default) or external |
Example request
curl -X POST https://offers.spoonity.com/v1/evaluate \
-H "X-API-Key: YOUR_OFFERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"evaluation_id": "K12-000482",
"channel": "kiosk",
"store_id": "store_12",
"customer": { "identifier": "cust_1001" },
"codes": ["WELCOME3"],
"selected": ["reward_free_cookie"],
"cart": {
"line_items": [
{ "line_id": "1", "id": "cola", "name": "Cola", "categories": [{ "id": "drinks" }], "price": 279, "quantity": 2 },
{ "line_id": "2", "id": "cookie", "name": "Cookie", "categories": [{ "id": "desserts" }], "price": 199, "quantity": 1 }
]
}
}'
Example response
200. The free cookie (a 150-point loyalty reward the guest selected) and a
$3 code both applied. "20% off drinks" and the combo are applicable: they
would apply if requested (the combo still needs a main and a side). The spend
tier is not reached.
{
"evaluation_id": "K12-000482",
"offers": [
{
"offer_id": "reward_free_cookie",
"name": "Free Cookie (150 pts)",
"status": "applied",
"source": { "type": "redemption", "vendor_perk_redemption_id": 501 },
"pos_reference": "discount_free_cookie",
"cost_points": 150,
"discount_total": 199
},
{
"offer_id": "promo_WELCOME3",
"name": "$3 Off with Code WELCOME3",
"status": "applied",
"source": { "type": "promotion_code", "code": "WELCOME3" },
"pos_reference": "discount_promo_WELCOME3",
"funding": "restaurant",
"discount_total": 300
},
{
"offer_id": "promo_DRINKS20",
"name": "20% off drinks",
"status": "applicable",
"source": { "type": "promotion_code" },
"pos_reference": "discount_promo_DRINKS20",
"discount_total": 112
},
{
"offer_id": "promo_SPEND20",
"name": "Spend more, save more",
"status": "inapplicable",
"source": { "type": "promotion_code" },
"pos_reference": "discount_promo_SPEND20",
"reason": {
"code": "TIER_NOT_REACHED",
"message": "Spend $20.00 to unlock",
"next_min_spend": 2000,
"shortfall": 1243
}
},
{
"offer_id": "promo_LUNCHCOMBO",
"name": "Lunch combo $10.99",
"status": "applicable",
"source": { "type": "promotion_code" },
"pos_reference": "discount_promo_LUNCHCOMBO",
"reason": {
"code": "BUNDLE_INCOMPLETE",
"message": "Add the remaining items to complete this combo",
"missing": [
{ "component": 0, "required": 1, "available": 0 },
{ "component": 1, "required": 1, "available": 0 }
]
}
}
],
"cart": {
"line_items": [
{
"line_id": "1", "id": "cola", "name": "Cola", "categories": [{ "id": "drinks" }],
"price": 279, "quantity": 2, "discounts": []
},
{
"line_id": "2", "id": "cookie", "name": "Cookie", "categories": [{ "id": "desserts" }],
"price": 199, "quantity": 1,
"discounts": [
{ "id": "discount_free_cookie", "name": "Free Cookie (150 pts)", "amount": 199,
"offer_id": "reward_free_cookie", "unit_index": 0, "quantity": 1 }
]
}
],
"discounts": [
{ "id": "discount_promo_WELCOME3", "name": "$3 Off with Code WELCOME3", "amount": 300, "offer_id": "promo_WELCOME3" }
],
"allocations": [
{ "line_id": "1", "offer_id": "promo_WELCOME3", "amount": 300 }
],
"subtotal": 757,
"discount_total": 499,
"total": 258
},
"effects": [
{
"type": "order_discount",
"offer_id": "promo_WELCOME3",
"amount": 300,
"pos_reference": "discount_promo_WELCOME3",
"allocations": [{ "line_id": "1", "offer_id": "promo_WELCOME3", "amount": 300 }],
"funding": "restaurant"
},
{
"type": "item_discount",
"offer_id": "reward_free_cookie",
"line_id": "2",
"unit_index": 0,
"quantity": 1,
"amount": 199,
"pos_reference": "discount_free_cookie"
}
],
"receipt_lines": [
"Free Cookie (150 pts) applied \u2014 you saved $1.99",
"$3 Off with Code WELCOME3 applied \u2014 you saved $3.00"
],
"lock": null,
"redemption_id": null,
"accrual_preview": null,
"order_payload": {
"receipt_number": "K12-000482",
"subtotal": 7.57,
"total": 2.58,
"line_items": [
{ "id": "cola", "name": "Cola", "categories": [{ "id": "drinks" }], "price": 2.79, "quantity": 2, "discounts": [] },
{ "id": "cookie", "name": "Cookie", "categories": [{ "id": "desserts" }], "price": 1.99, "quantity": 1,
"discounts": [{ "id": "discount_free_cookie", "name": "Free Cookie (150 pts)", "amount": 1.99 }] }
],
"discounts": [
{ "id": "discount_promo_WELCOME3", "name": "$3 Off with Code WELCOME3", "amount": 3 }
]
}
}
The same request with "lock": { "ttl_seconds": 300 } returns the same
body with these three fields filled in:
{
"evaluation_id": "K12-000482",
"lock": { "key": "lock_73effdbf-a2b9-463c-b462-0a2a03032669", "expires_at": "2026-09-30T10:35:19.390Z" },
"redemption_id": "ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0"
}
Reading the response:
offers[]: every candidate offer with its status. Code-gated offers whose code was not entered are left out entirely.cart: the repriced cart. Item discounts are online_items[].discounts(idis thepos_reference), order discounts oncart.discounts, andallocationsspreads each order discount across lines for refunds.totalissubtotalminusexternal_discount_total(present only when lines carried POS discounts) minusdiscount_total.effects[]: the same result as instructions for a POS:item_discount(line, first unit, unit count, amount),order_discount(amount plus allocations) andadd_item_hint(a free item offer whose SKU is not in the cart; also shown asadd_item_hint: { sku }on the offer).fundingisrestaurant,channel,sharedorloyalty; absent meansrestaurant. It is attribution only and never changes the amounts.receipt_lines: printable lines. Treat them as display text; the wording can change. The engine separates the two halves with a dash character, shown escaped above.lockandredemption_id:nullunlesslockwas requested and the result has something to record.accrual_preview: an estimate of points earned, when the loyalty source provides an earn rate; otherwisenull. The loyalty platform is authoritative.order_payload: decimal dollars, for the loyalty platform's order endpoint. Submit it verbatim.
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | Body failed validation; issues[] says where |
| 401 | UNAUTHORIZED | Missing or invalid credential, or ?api_key= in production |
| 409 | OFFERS_RESERVED | With lock: another in-flight order holds one of the single-use offers. Carries conflict_offer_ids. Evaluate again; the next result prices without that offer |
| 409 | EVALUATION_TERMINAL | With lock: this evaluation_id is already committed, cancelled, rolled_back or expired. Carries state. Start a new evaluation_id |
| 503 | OFFERS_UNAVAILABLE | The catalog or the vendor's policy could not be read. Retryable; proceed without discounts |
GET /v1/offers
List the vendor's offers without pricing a cart, for a rewards screen.
Auth: Vendor API key, or OIDC service identity.
Query parameters
| Name | Type | Description |
|---|---|---|
customer | string | Loyalty customer identifier |
store_id | string | Store |
channel | string | Channel |
Code-gated offers are never listed. There is no status or reason here; call
POST /v1/evaluate with selection_mode: "list" for that.
Example request
curl "https://offers.spoonity.com/v1/offers?customer=cust_1001&channel=kiosk" \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
{
"offers": [
{ "offer_id": "reward_free_cookie", "name": "Free Cookie (150 pts)", "cost_points": 150,
"pos_reference": "discount_free_cookie", "effect_type": "free_item", "requires_code": false },
{ "offer_id": "promo_DRINKS20", "name": "20% off drinks",
"pos_reference": "discount_promo_DRINKS20", "effect_type": "percent_off", "requires_code": false },
{ "offer_id": "promo_SPEND20", "name": "Spend more, save more",
"pos_reference": "discount_promo_SPEND20", "effect_type": "tiered", "requires_code": false },
{ "offer_id": "promo_LUNCHCOMBO", "name": "Lunch combo $10.99",
"pos_reference": "discount_promo_LUNCHCOMBO", "effect_type": "bundle", "requires_code": false }
]
}
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | Invalid query parameter |
| 401 | UNAUTHORIZED | Missing or invalid credential |
GET /v1/redemptions/{id}
Read one redemption record.
Auth: Vendor API key, or OIDC service identity. A redemption that
belongs to another vendor is a 404, the same as one that does not exist.
Path parameters
| Name | Description |
|---|---|
id | redemption_id from a locked evaluate (ored_...) |
Example request
curl https://offers.spoonity.com/v1/redemptions/ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0 \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
The redemption from the locked evaluate above, after the order was submitted:
{
"redemption": {
"redemption_id": "ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0",
"vendor_id": "dev-vendor",
"evaluation_id": "K12-000482",
"state": "committed",
"offers": [
{
"offer_id": "reward_free_cookie",
"version": 3,
"pos_reference": "discount_free_cookie",
"discount_total": 199,
"single_use": false,
"line_discounts": [
{ "id": "discount_free_cookie", "name": "Free Cookie (150 pts)", "amount": 199,
"offer_id": "reward_free_cookie", "unit_index": 0, "quantity": 1, "line_id": "2" }
]
},
{
"offer_id": "promo_WELCOME3",
"version": 1,
"pos_reference": "discount_promo_WELCOME3",
"discount_total": 300,
"single_use": false,
"allocations": [{ "line_id": "1", "offer_id": "promo_WELCOME3", "amount": 300 }]
}
],
"cart_snapshot": {
"line_items": [
{ "line_id": "1", "id": "cola", "name": "Cola", "categories": [{ "id": "drinks" }],
"price": 279, "quantity": 2, "discounts": [] },
{ "line_id": "2", "id": "cookie", "name": "Cookie", "categories": [{ "id": "desserts" }],
"price": 199, "quantity": 1,
"discounts": [{ "id": "discount_free_cookie", "name": "Free Cookie (150 pts)", "amount": 199,
"offer_id": "reward_free_cookie", "unit_index": 0, "quantity": 1 }] }
],
"discounts": [{ "id": "discount_promo_WELCOME3", "name": "$3 Off with Code WELCOME3", "amount": 300, "offer_id": "promo_WELCOME3" }],
"allocations": [{ "line_id": "1", "offer_id": "promo_WELCOME3", "amount": 300 }],
"subtotal": 757,
"discount_total": 499,
"total": 258
},
"customer_id": "cust_1001",
"created_at": 1790764219390,
"expires_at": 1790764519390,
"revision": 3,
"lock_key": "lock_73effdbf-a2b9-463c-b462-0a2a03032669",
"committed_at": 1790764226347,
"order_reference": "ord_88213"
}
}
vendor_id is the vendor the key belongs to. mismatch appears when the
submitted order's discount ids differed from what was evaluated; the record
still commits. rolled_back_at, cancelled_at and returned_line_ids
appear once set.
Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 404 | NOT_FOUND | No such redemption for this vendor |
POST /v1/redemptions/{id}/rollback
Void a redemption: the order was refunded or voided. Single-use offers, usage counts and budget come back.
Auth: Vendor API key, or OIDC service identity.
A committed or partially returned record becomes rolled_back; a pending
one becomes cancelled. Calling it again is safe. A state that does not
allow the transition is returned unchanged.
Example request
curl -X POST https://offers.spoonity.com/v1/redemptions/ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0/rollback \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
{ "redemption": { "redemption_id": "ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0", "state": "rolled_back" } }
Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 404 | NOT_FOUND | No such redemption for this vendor |
POST /v1/redemptions/{id}/cancel
Cancel a pending redemption and release its hold: the guest abandoned the order. A cancelled record can never commit.
Auth: Vendor API key, or OIDC service identity.
Only a pending record changes; any other state is returned unchanged.
Example request
curl -X POST https://offers.spoonity.com/v1/redemptions/ored_bbfb7ca3-21c8-48aa-9dc3-137047d550fe/cancel \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
{ "redemption": { "redemption_id": "ored_bbfb7ca3-21c8-48aa-9dc3-137047d550fe", "state": "cancelled" } }
Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 404 | NOT_FOUND | No such redemption for this vendor |
POST /v1/redemptions/{id}/returns
Record a partial return by line. Reports the discount that was on each returned line, for a refund clawback.
Auth: Vendor API key, or OIDC service identity.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
line_ids | string[] | Yes | 1 to 200 line_id values from the evaluated cart. A line already returned contributes nothing the second time |
The record becomes partially_returned. Single-use offers are not restored
and the budget is not refunded: that money left the business on a paid
order. Use rollback for a full void.
Example request
curl -X POST https://offers.spoonity.com/v1/redemptions/ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0/returns \
-H "X-API-Key: YOUR_OFFERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "line_ids": ["2"] }'
Example response
{
"redemption": { "redemption_id": "ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0", "state": "partially_returned" },
"returned": [{ "line_id": "2", "offer_id": "reward_free_cookie", "discount_amount": 199 }]
}
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | line_ids missing or empty |
| 400 | UNKNOWN_LINES | Some ids are not in this redemption. Carries unknown_line_ids |
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 404 | NOT_FOUND | No such redemption for this vendor |
| 409 | INVALID_STATE | The record is not committed or partially_returned |
DELETE /v1/locks/{key}
Release a lock and cancel its redemption: the guest cancelled before paying.
Auth: Vendor API key, or OIDC service identity.
Path parameters
| Name | Description |
|---|---|
key | lock.key from a locked evaluate (lock_...) |
Example request
curl -X DELETE https://offers.spoonity.com/v1/locks/lock_2cbb388d-4c86-490e-b9a0-7c71aea9154d \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
{ "released": true, "redemption": { "redemption_id": "ored_e7bf6215-68bd-470f-bf19-f63baa7e2c35", "state": "cancelled" } }
Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 404 | NOT_FOUND | Unknown, already released or expired lock, or another vendor's |
POST /webhooks/events
How a pending redemption commits or voids: order.submitted after an order
carrying the order_payload lands, and order.voided when it is voided. It
is correlated on receipt_number == evaluation_id.
Auth: A shared secret in x-webhook-secret, held by Spoonity. Not the
/v1 credentials. This route is listed so the lifecycle is complete; an
integrator does not call it directly. Before relying on single-use offers or
usage limits through /v1/evaluate, confirm with Spoonity that these events
are being sent for your vendor. The POS check surface does not depend on
them: close commits directly.
| Field | Type | Description |
|---|---|---|
type | string | order.submitted or order.voided |
vendor_id | string | Vendor |
receipt_number | string | The evaluation_id |
discount_ids | string[] | order.submitted only: the discount ids on the order, compared with what was evaluated |
order_reference | string | order.submitted only: the order id, stored on the record |
event_id | string | De-duplication key; a repeated event is a no-op |
The answer is always 200 for a valid event, including one whose receipt
has no redemption (orders without offers are normal):
{ "processed": true, "redemption": { "redemption_id": "ored_24b5aabb-89dc-4684-85c7-0fa6b84937b0", "state": "committed", "mismatch": null } }
A bad secret is 401 UNAUTHORIZED. An invalid payload is
400 INVALID_REQUEST, and on this route issues[] is a list of strings
rather than { path, message } objects.
Admin catalog API
Manage merchant promotions, the vendor's promotion policy, and read-only loyalty rewards. Prism's Promotions section is built on these routes.
Every route is scoped to the calling vendor. A promotion id that belongs to
another vendor answers 404, exactly like one that does not exist. Every
non-GET route answers 403 FORBIDDEN to an OIDC caller with the viewer
role, except simulate.
A promotion is evaluated as the offer promo_<promotion_id>, and lands on
the POS as pos_reference (default discount_promo_<promotion_id>).
Statuses: draft (never evaluated), active (live, subject to its own
schedule), paused (withdrawn, definition kept), archived (retired and
read-only; never deleted, because redemptions reference its versions).
Every write, including a status change, bumps version and appends a
history entry. There is no delete.
Caching: evaluation reads the catalog through a cache of up to 5 seconds,
so an edit can take that long to affect POST /v1/evaluate and the POS
check. Admin reads and simulate see it at once.
The promotion object
Request and response bodies use the same field names, so a GET body minus
the read-only fields (promotion_id, vendor_id, status, version,
created_at, updated_at, created_by, updated_by) is a valid PUT body.
Money is integer cents wherever a field is not a percent.
Identity and lifecycle
| Field | Type | Description |
|---|---|---|
identifier | string | Optional on create: your id for the promotion. Minted when omitted. new, simulate, policy, loyalty-rewards, history, usage, . and .. are reserved (any case) |
name | string | Guest-facing name, 1 to 256 characters. Required |
notes | string | Operator note, up to 2000 characters |
status | string | On create only: draft, active or paused. Use the lifecycle routes afterwards |
expected_version | integer | Required on PUT. Refused on create |
pos_reference | string | POS discount identifier. Default discount_promo_<promotion_id> |
Effect: discount_type
Each type accepts only its own fields; a field that belongs to another type
is a 400.
discount_type | Fields | Effect |
|---|---|---|
PERCENT | discount_amount (0 to 100), scope, amount_limit, max_quantity, min_quantity, modifier_policy | Percent off the targeted items (scope: "item") or the order (scope: "order"). amount_limit caps the total discount in cents |
AMOUNT | discount_amount (cents), scope, max_quantity, min_quantity, modifier_policy | Cents off each targeted unit (item) or off the order (order) |
FIXED_PRICE | discount_amount (cents), max_quantity, include_modifiers | Targeted units sell at this price. By default the price replaces the item price and modifiers are charged on top; include_modifiers: true makes it cover item and modifiers |
FREE_ITEM | free_item_sku, max_quantity | Zeroes that SKU when it is in the cart. When it is not, the offer is applicable with an add_item_hint |
BUY_X_GET_Y | bogo | Buy the trigger set, get the reward set free or at percent off. See below |
TIERED | spend_tiers | Order-level discount by spend threshold. See below |
BUNDLE | bundle | Combo price for one complete set of components. See below |
Item-scope knobs on PERCENT and AMOUNT:
scope:itemororder. When omitted,productsorcategoriesimpliesitem, otherwiseorder.max_quantity: at most this many units discounted per application.min_quantity: apply only with at least this many eligible units, elseMIN_QUANTITY_NOT_MET.modifier_policy:include(default) computes on item plus modifiers;excludeon the item price alone.
These three are refused on an order-scope effect.
bogo:
{
"trigger": { "categories": ["drinks"], "quantity": 1 },
"reward": { "categories": ["drinks"], "quantity": 1, "percent": 100 },
"selection": "cheapest",
"max_applications": 2
}
trigger and reward take products, categories, exclude_products,
exclude_categories and quantity (1 to 1000). reward.percent defaults
to 100. selection is cheapest (default) or most_expensive.
max_applications is 1 to 100.
spend_tiers (1 to 20 tiers, distinct min_spend):
[
{ "min_spend": 2000, "amount": 300 },
{ "min_spend": 4000, "percent": 15, "amount_limit": 1000 }
]
Each tier has exactly one of percent or amount; amount_limit caps a
percent tier only. The highest tier reached applies. None reached is
TIER_NOT_REACHED with next_min_spend and shortfall. A tiered promotion
always discounts the order, so it takes no scope and no top-level
products or categories. The field is spend_tiers, not tiers, because
tiers is the loyalty-tier restriction below.
bundle:
{
"components": [
{ "categories": ["mains"], "quantity": 1 },
{ "categories": ["sides"], "quantity": 1 },
{ "categories": ["drinks"], "quantity": 1 }
],
"price": 1099,
"max_applications": 1,
"selection": "most_expensive"
}
1 to 10 components, each with the same item filters as a bogo side plus
quantity. price is the combo price in cents. selection picks which
units fill each component: cheapest (default) or most_expensive. With
cheapest, sets are taken until one would not be discounted, so a combo
whose cheapest set already costs less than price gives nothing even when
pricier units are in the cart; choose most_expensive if the combo should
always apply when the cart is worth more. An incomplete set is
BUNDLE_INCOMPLETE with missing[]. Item filters go on the components;
top-level products or categories are refused.
Targeting
| Field | Type | Description |
|---|---|---|
products | string[] | SKUs (cart line id) that can receive the discount |
categories | string[] | Category ids that can receive the discount |
exclude_products | string[] | SKUs that never receive it |
exclude_categories | string[] | Categories that never receive it |
Exclusions win over inclusions. Up to 50 entries each.
Conditions
| Field | Type | Description |
|---|---|---|
min_spend | integer cents | Minimum subtotal, else MIN_SPEND_NOT_MET with shortfall. The vendor policy's min_spend_basis decides which subtotal |
tiers | string[] | Loyalty tier ids allowed, else TIER_NOT_ELIGIBLE |
segments | string[] | Customer segments allowed, else CONDITION_NOT_MET |
first_order_only | boolean | Only for a customer with no previous orders. Fails closed when the order count is unknown |
customer_tags | string[] | The customer carries at least one of these tags (1 to 50, up to 64 characters each) |
requires_customer | boolean | Refuse unidentified guests with CUSTOMER_REQUIRED. Default false: promotions are open to guests |
Schedule and placement
| Field | Type | Description |
|---|---|---|
active | { start?, end? } | ISO 8601 instants with offset. Outside it: OUTSIDE_ACTIVE_WINDOW |
dayparts | array | [{ days?, start?, end? }]. days 0 (Sunday) to 6; start inclusive and end exclusive, HH:MM 24-hour. Outside every daypart: OUTSIDE_DAYPART |
stores | string[] | Store ids allowed, else STORE_NOT_ELIGIBLE |
channels | string[] | Channels allowed, else CHANNEL_NOT_ELIGIBLE |
An active promotion outside its daypart, store or channel is still evaluated and reported with the reason, so a screen can say "available from 3pm" rather than hiding it.
Stacking, redemption and limits
| Field | Type | Description |
|---|---|---|
stacking.exclusive | boolean | Nothing else applies once this does |
stacking.priority | integer | -1000 to 1000, default 0. Higher goes first |
stacking.group | string | One applied promotion per group |
requires_code | string | The code that unlocks it. Without the code the offer is not shown at all |
auto_apply | boolean | Applies without being selected in manual mode |
single_use | boolean | One use per customer. Implies requires_customer |
usage_limits.max_total | integer | Committed uses across all customers, else USAGE_LIMIT_REACHED |
usage_limits.max_per_customer | integer | Committed uses per customer. Implies requires_customer |
usage_limits.max_per_day | integer | Committed uses per UTC day |
usage_limits.budget_cents | integer | Total discount this promotion may ever give, else BUDGET_EXHAUSTED |
funding | string | Who pays: restaurant (default), channel, shared, loyalty. Attribution only |
funding_split.restaurant_bps | integer | Required when funding is shared, refused otherwise. Restaurant share, 0 to 10000 basis points |
Usage limits and budgets are computed from committed redemptions, so a rollback restores them.
Response envelope
Single-promotion routes answer { "promotion": {...}, "offer": {...} }:
the promotion in the wire vocabulary above, and the offer the engine
actually evaluates. When a promotion does not apply as expected, compare the
two.
GET /v1/admin/promotions
List the vendor's promotions.
Auth: Vendor API key, or OIDC service identity (any role).
Query parameters
| Name | Type | Description |
|---|---|---|
status | string | draft, active, paused or archived |
limit | integer | 1 to 500 |
Example request
curl "https://offers.spoonity.com/v1/admin/promotions?status=active&limit=50" \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
Each entry is the promotion only, without the offer projection:
{
"promotions": [
{
"identifier": "SPEND20",
"promotion_id": "SPEND20",
"vendor_id": "dev-vendor",
"name": "Spend more, save more",
"status": "active",
"version": 1,
"pos_reference": "discount_promo_SPEND20",
"discount_type": "TIERED",
"spend_tiers": [
{ "min_spend": 2000, "amount": 300 },
{ "min_spend": 4000, "percent": 15, "amount_limit": 1000 }
],
"created_at": 1790764191204,
"updated_at": 1790764191204
}
]
}
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | Invalid status or limit |
| 401 | UNAUTHORIZED | Missing or invalid credential |
POST /v1/admin/promotions
Create a promotion.
Auth: Vendor API key, or OIDC service identity with admin or editor.
Request body
The promotion object, without expected_version.
Example request
curl -X POST https://offers.spoonity.com/v1/admin/promotions \
-H "X-API-Key: YOUR_OFFERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"identifier": "DRINKS20",
"name": "20% off drinks",
"discount_type": "PERCENT",
"discount_amount": 20,
"scope": "item",
"categories": ["drinks"],
"max_quantity": 2,
"stacking": { "group": "drinks", "priority": 10 },
"status": "active"
}'
Example response
201:
{
"promotion": {
"identifier": "DRINKS20",
"promotion_id": "DRINKS20",
"vendor_id": "dev-vendor",
"name": "20% off drinks",
"status": "active",
"version": 1,
"pos_reference": "discount_promo_DRINKS20",
"discount_type": "PERCENT",
"discount_amount": 20,
"scope": "item",
"max_quantity": 2,
"categories": ["drinks"],
"stacking": { "priority": 10, "group": "drinks" },
"created_at": 1790764191191,
"updated_at": 1790764191191
},
"offer": {
"effect": { "type": "percent_off", "scope": "item", "percent": 20, "max_quantity": 2 },
"targeting": { "categories": ["drinks"] },
"stacking": { "priority": 10, "group": "drinks" },
"offer_id": "promo_DRINKS20",
"version": 1,
"name": "20% off drinks",
"source": { "type": "promotion_code" },
"pos_reference": "discount_promo_DRINKS20"
}
}
A combo, created as a draft so it can be simulated before it goes live:
curl -X POST https://offers.spoonity.com/v1/admin/promotions \
-H "X-API-Key: YOUR_OFFERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"identifier": "LUNCHCOMBO",
"name": "Lunch combo $10.99",
"discount_type": "BUNDLE",
"bundle": {
"components": [
{ "categories": ["mains"], "quantity": 1 },
{ "categories": ["sides"], "quantity": 1 },
{ "categories": ["drinks"], "quantity": 1 }
],
"price": 1099,
"max_applications": 1,
"selection": "most_expensive"
},
"channels": ["kiosk", "pos"],
"status": "draft"
}'
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | Validation failed (see below), expected_version sent, or a reserved identifier |
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 403 | FORBIDDEN | OIDC caller with the viewer role |
| 409 | PROMOTION_EXISTS | The identifier is taken. Carries identifier. Ids are unique across all vendors, and the message does not say who holds it |
A validation failure lists every problem:
{
"error": {
"code": "INVALID_REQUEST",
"message": "Promotion validation failed",
"issues": [
{ "path": "discount_amount", "message": "percent discounts must be between 0 and 100" },
{ "path": "min_quantity", "message": "min_quantity applies to item-scoped effects only" }
]
}
}
GET /v1/admin/promotions/{id}
Read one promotion.
Auth: Vendor API key, or OIDC service identity (any role).
Path parameters
| Name | Description |
|---|---|
id | The promotion_id |
Example request
curl https://offers.spoonity.com/v1/admin/promotions/DRINKS20 \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
{ "promotion": {...}, "offer": {...} }, the same shape as the create
response.
Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 404 | NOT_FOUND | No such promotion for this vendor |
PUT /v1/admin/promotions/{id}
Replace a promotion. Omitted fields are removed, so send the whole
definition: read it, change it, send it back with expected_version set to
the version you read.
Auth: Vendor API key, or OIDC service identity with admin or editor.
Request body
The promotion object with expected_version.
identifier and status are ignored.
Example request
curl -X PUT https://offers.spoonity.com/v1/admin/promotions/DRINKS20 \
-H "X-API-Key: YOUR_OFFERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "25% off drinks",
"discount_type": "PERCENT",
"discount_amount": 25,
"scope": "item",
"categories": ["drinks"],
"max_quantity": 2,
"stacking": { "group": "drinks", "priority": 10 },
"expected_version": 1
}'
Example response
{
"promotion": {
"identifier": "DRINKS20",
"promotion_id": "DRINKS20",
"vendor_id": "dev-vendor",
"name": "25% off drinks",
"status": "active",
"version": 2,
"pos_reference": "discount_promo_DRINKS20",
"discount_type": "PERCENT",
"discount_amount": 25,
"scope": "item",
"max_quantity": 2,
"categories": ["drinks"],
"stacking": { "priority": 10, "group": "drinks" },
"created_at": 1790764191191,
"updated_at": 1790764267091
},
"offer": {
"effect": { "type": "percent_off", "scope": "item", "percent": 25, "max_quantity": 2 },
"targeting": { "categories": ["drinks"] },
"stacking": { "priority": 10, "group": "drinks" },
"offer_id": "promo_DRINKS20",
"version": 2,
"name": "25% off drinks",
"source": { "type": "promotion_code" },
"pos_reference": "discount_promo_DRINKS20"
}
}
A stale expected_version carries the current version and the stored
promotion, so a UI can show what changed:
{
"error": {
"code": "VERSION_CONFLICT",
"message": "This promotion changed since you read it; re-read and retry",
"version": 2,
"promotion": {
"identifier": "DRINKS20", "promotion_id": "DRINKS20", "vendor_id": "dev-vendor",
"name": "25% off drinks", "status": "active", "version": 2,
"pos_reference": "discount_promo_DRINKS20", "discount_type": "PERCENT", "discount_amount": 25,
"scope": "item", "max_quantity": 2, "categories": ["drinks"],
"stacking": { "priority": 10, "group": "drinks" },
"created_at": 1790764191191, "updated_at": 1790764267091
}
}
}
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | Validation failed |
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 403 | FORBIDDEN | OIDC caller with the viewer role |
| 404 | NOT_FOUND | No such promotion for this vendor |
| 409 | VERSION_REQUIRED | expected_version missing. Carries version. A missing version is never treated as "overwrite" |
| 409 | VERSION_CONFLICT | expected_version is stale. Carries version and promotion |
| 409 | PROMOTION_ARCHIVED | Archived promotions are read-only. Carries version. Pause it first to edit it |
POST /v1/admin/promotions/{id}/activate
Set the status to active.
Auth: Vendor API key, or OIDC service identity with admin or editor.
Request body
Optional: { "expected_version": <integer> }. When sent, a stale version is
409 VERSION_CONFLICT.
Example request
curl -X POST https://offers.spoonity.com/v1/admin/promotions/LUNCHCOMBO/activate \
-H "X-API-Key: YOUR_OFFERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "expected_version": 1 }'
Example response
{
"promotion": {
"identifier": "LUNCHCOMBO",
"promotion_id": "LUNCHCOMBO",
"vendor_id": "dev-vendor",
"name": "Lunch combo $10.99",
"status": "active",
"version": 2,
"pos_reference": "discount_promo_LUNCHCOMBO",
"discount_type": "BUNDLE",
"bundle": {
"components": [
{ "categories": ["mains"], "quantity": 1 },
{ "categories": ["sides"], "quantity": 1 },
{ "categories": ["drinks"], "quantity": 1 }
],
"price": 1099,
"max_applications": 1,
"selection": "most_expensive"
},
"channels": ["kiosk", "pos"],
"created_at": 1790764191216,
"updated_at": 1790764208496
},
"offer": {
"effect": {
"type": "bundle",
"components": [
{ "filter": { "categories": ["mains"] }, "quantity": 1 },
{ "filter": { "categories": ["sides"] }, "quantity": 1 },
{ "filter": { "categories": ["drinks"] }, "quantity": 1 }
],
"price": 1099,
"max_applications": 1,
"selection": "most_expensive"
},
"channels": ["kiosk", "pos"],
"offer_id": "promo_LUNCHCOMBO",
"version": 2,
"name": "Lunch combo $10.99",
"source": { "type": "promotion_code" },
"pos_reference": "discount_promo_LUNCHCOMBO"
}
}
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | expected_version is not an integer |
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 403 | FORBIDDEN | OIDC caller with the viewer role |
| 404 | NOT_FOUND | No such promotion for this vendor |
| 409 | VERSION_CONFLICT | expected_version is stale |
POST /v1/admin/promotions/{id}/pause
Set the status to paused. Also the way to un-archive a promotion.
Auth: Vendor API key, or OIDC service identity with admin or editor.
Same body, response and errors as activate.
Example request
curl -X POST https://offers.spoonity.com/v1/admin/promotions/DRINKS20/pause \
-H "X-API-Key: YOUR_OFFERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "expected_version": 2 }'
Example response
{ "promotion": {...}, "offer": {...} } with "status": "paused" and
"version": 3.
Errors
As for activate.
POST /v1/admin/promotions/{id}/archive
Set the status to archived. An archived promotion is read-only and never
evaluated. It is kept, not deleted, so a disputed redemption can be replayed
against the exact rule version that paid out.
Auth: Vendor API key, or OIDC service identity with admin or editor.
Same body, response and errors as activate.
Example request
curl -X POST https://offers.spoonity.com/v1/admin/promotions/DRINKS20/archive \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
{ "promotion": {...}, "offer": {...} } with "status": "archived". A
later PUT answers:
{ "error": { "code": "PROMOTION_ARCHIVED", "message": "Archived promotions are read-only; restore it with /pause first", "version": 4 } }
Errors
As for activate.
GET /v1/admin/promotions/{id}/history
Every version of a promotion, newest first, each with a full snapshot.
Auth: Vendor API key, or OIDC service identity (any role).
Example request
curl https://offers.spoonity.com/v1/admin/promotions/DRINKS20/history \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
Abridged to the two oldest entries; each promotion is the full snapshot in
the wire vocabulary.
{
"history": [
{
"version": 2,
"status": "active",
"change": "updated",
"at": 1790764267091,
"promotion": { "identifier": "DRINKS20", "promotion_id": "DRINKS20", "name": "25% off drinks", "version": 2, "discount_amount": 25 }
},
{
"version": 1,
"status": "active",
"change": "created",
"at": 1790764191191,
"promotion": { "identifier": "DRINKS20", "promotion_id": "DRINKS20", "name": "20% off drinks", "version": 1, "discount_amount": 20 }
}
]
}
change is created, updated or status_changed. by appears when the
change was made by a named person (an OIDC call with X-Spoonity-User); an
API key leaves it out.
Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 404 | NOT_FOUND | No such promotion for this vendor |
POST /v1/admin/promotions/simulate
Evaluate any cart against the vendor's promotions with no side effects: nothing is reserved or recorded. Use it to check a draft before activating it.
Auth: Vendor API key, or OIDC service identity (any role, including
viewer).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
cart | object | Yes | Same as POST /v1/evaluate |
customer | object | What-if customer: customer_id, tier_id, segments, order_count, tags, balances: [{ currency_id, balance }], and identifier to resolve a real customer first. The what-if fields win over what the real customer has | |
codes, selected, selection_mode, channel, store_id | Same as POST /v1/evaluate | ||
now | ISO 8601 | Evaluate as of this instant (dayparts, active windows). Default now | |
include_drafts | boolean | Add the vendor's draft promotions to the candidates | |
promotion_ids | string[] | Evaluate exactly these promotions, whatever their status, and no loyalty rewards | |
evaluation_id | string | Echoed back. Default sim_<uuid> |
The vendor's saved policy and the usage limits apply, read-only.
Example request
curl -X POST https://offers.spoonity.com/v1/admin/promotions/simulate \
-H "X-API-Key: YOUR_OFFERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"cart": {
"line_items": [
{ "line_id": "1", "id": "burger", "name": "Classic Burger", "categories": [{ "id": "mains" }], "price": 899, "quantity": 1 },
{ "line_id": "2", "id": "fries", "name": "Fries", "categories": [{ "id": "sides" }], "price": 349, "quantity": 1 },
{ "line_id": "3", "id": "cola", "name": "Cola", "categories": [{ "id": "drinks" }], "price": 279, "quantity": 2 },
{ "line_id": "4", "id": "cookie", "name": "Cookie", "categories": [{ "id": "desserts" }], "price": 199, "quantity": 1 }
]
},
"channel": "kiosk",
"include_drafts": true,
"now": "2026-10-02T17:00:00Z"
}'
Example response
The response is the evaluate result (evaluation_id, offers, cart,
effects, receipt_lines) plus explain and simulation. Here nothing is
selected in manual mode, so every eligible promotion is applicable with
its standalone value. Abridged: cart.line_items is omitted and explain
shows three of its five entries.
{
"evaluation_id": "sim_33bf90b3-5021-4b35-b76f-56f2029a5803",
"offers": [
{ "offer_id": "reward_free_cookie", "name": "Free Cookie (150 pts)", "status": "inapplicable",
"source": { "type": "redemption", "vendor_perk_redemption_id": 501 },
"pos_reference": "discount_free_cookie", "cost_points": 150,
"reason": { "code": "INSUFFICIENT_BALANCE", "message": "Not enough points for this reward", "required": 150, "balance": 0 } },
{ "offer_id": "promo_DRINKS20", "name": "20% off drinks", "status": "applicable",
"source": { "type": "promotion_code" }, "pos_reference": "discount_promo_DRINKS20", "discount_total": 112 },
{ "offer_id": "promo_SPEND20", "name": "Spend more, save more", "status": "applicable",
"source": { "type": "promotion_code" }, "pos_reference": "discount_promo_SPEND20", "discount_total": 300 },
{ "offer_id": "promo_LUNCHCOMBO", "name": "Lunch combo $10.99", "status": "applicable",
"source": { "type": "promotion_code" }, "pos_reference": "discount_promo_LUNCHCOMBO", "discount_total": 428 }
],
"cart": { "discounts": [], "allocations": [], "subtotal": 2005, "discount_total": 0, "total": 2005 },
"effects": [],
"receipt_lines": [],
"explain": [
{ "offer_id": "promo_WELCOME3", "name": "$3 Off with Code WELCOME3", "status": "inapplicable",
"reason": { "code": "CODE_REQUIRED", "message": "Enter the promotion code to see this offer" },
"promotion_id": "WELCOME3", "promotion_status": "active" },
{ "offer_id": "promo_DRINKS20", "name": "20% off drinks", "status": "applicable",
"discount_total": 112, "promotion_id": "DRINKS20", "promotion_status": "active" },
{ "offer_id": "promo_LUNCHCOMBO", "name": "Lunch combo $10.99", "status": "applicable",
"discount_total": 428, "promotion_id": "LUNCHCOMBO", "promotion_status": "draft" }
],
"simulation": { "now": "2026-10-02T17:00:00.000Z", "include_drafts": true, "policy_version": null }
}
explain has one entry per candidate. It includes code-gated promotions
whose code was not entered (as CODE_REQUIRED), which offers leaves out.
arbitration_rank (1-based) appears on offers arbitration tried to apply
(applied or skipped). policy_version is null when the vendor has no
saved policy.
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | Validation failed, or a promotion_ids entry is unknown or another vendor's (listed in unknown_promotion_ids) |
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 503 | OFFERS_UNAVAILABLE | The catalog or policy could not be read |
GET /v1/admin/promotions/{id}/usage
Uses and discount given for one promotion, from the redemption ledger.
Auth: Vendor API key, or OIDC service identity (any role).
Query parameters
| Name | Type | Description |
|---|---|---|
days | integer | 1 to 90, default 30. Length of the per_day series |
uses and discount_cents are all-time and count committed and
partially_returned records, the same way the usage limits do. per_day is
zero-filled, oldest first, in UTC days. limits echoes usage_limits (or
null); budget is null without a budget_cents.
Example request
curl "https://offers.spoonity.com/v1/admin/promotions/WELCOME3/usage?days=3" \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
{
"promotion_id": "WELCOME3",
"offer_id": "promo_WELCOME3",
"uses": 2,
"discount_cents": 600,
"per_day": [
{ "day": "2026-09-28", "uses": 0, "discount_cents": 0 },
{ "day": "2026-09-29", "uses": 0, "discount_cents": 0 },
{ "day": "2026-09-30", "uses": 2, "discount_cents": 600 }
],
"window": { "days": 3, "since": "2026-09-28", "until": "2026-09-30" },
"limits": { "max_per_day": 100, "budget_cents": 50000 },
"budget": { "budget_cents": 50000, "spent_cents": 600, "remaining_cents": 49400 }
}
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | days out of range |
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 404 | NOT_FOUND | No such promotion for this vendor |
| 503 | OFFERS_UNAVAILABLE | The redemption ledger is not available |
GET /v1/admin/promotions/{id}/redemptions
Recent redemption records holding this promotion, in every state, newest first.
Auth: Vendor API key, or OIDC service identity (any role).
Query parameters
| Name | Type | Description |
|---|---|---|
limit | integer | 1 to 200, default 50 |
before | string | The previous page's next_before, or an epoch-millisecond instant |
next_before is null on the last page. customer_id, order_reference,
committed_at, rolled_back_at, cancelled_at, mismatch and
returned_line_ids appear only when set.
Example request
curl "https://offers.spoonity.com/v1/admin/promotions/WELCOME3/redemptions?limit=1" \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
{
"redemptions": [
{
"redemption_id": "ored_cc3e0ab9-63f8-4697-8b06-544bb832b6d7",
"evaluation_id": "K12-000491",
"state": "committed",
"order_reference": "ord_88491",
"discount_cents": 300,
"offer_version": 1,
"pos_reference": "discount_promo_WELCOME3",
"cart": { "subtotal": 757, "discount_total": 300, "total": 457 },
"created_at": 1790764254348,
"expires_at": 1790764554348,
"committed_at": 1790764254365
}
],
"next_before": "1790764254348:ored_cc3e0ab9-63f8-4697-8b06-544bb832b6d7"
}
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | Invalid limit or before |
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 404 | NOT_FOUND | No such promotion for this vendor |
| 503 | OFFERS_UNAVAILABLE | The redemption ledger is not available |
The promotion policy
One policy per vendor sets the stacking and safety rules for every
evaluation of that vendor's carts: POST /v1/evaluate, the POS check and
simulate. A vendor that never saved one gets the defaults at version: 0.
| Setting | Values | Default | Effect |
|---|---|---|---|
max_applied_offers | 1 to 50 | 5 | Most offers applied to one order. Beyond it: MAX_OFFERS_REACHED |
order_percent_mode | cascade, additive | cascade | cascade: each order-level percent applies to what the previous ones left. additive: each applies to the same post-item-discount base |
max_order_discount_percent | 0 to 100 | none | Ceiling on the order's total discount as a percent of subtotal. Order-level discounts are trimmed, last applied first (ORDER_CAP_REACHED); item discounts are never trimmed |
excluded | { products?, categories?, exclude_products?, exclude_categories? } | none | Items no promotion may touch (gift cards, alcohol, deposits): never discounted, never counted in an order-level base |
min_spend_basis | subtotal, eligible | subtotal | What min_spend and spend tiers compare against. eligible is the subtotal minus excluded items and POS discounts |
local_discount_policy | respect, ignore | respect | respect: a line carrying a POS discount gets no item-level offer (LOCALLY_DISCOUNTED). ignore: it stays discountable, capped at what the POS left |
A PUT replaces the whole policy; a setting left out goes back to its
default. A GET body minus vendor_id, version, updated_at and
updated_by is a valid PUT body.
GET /v1/admin/promotion-policy
Read the vendor's policy.
Auth: Vendor API key, or OIDC service identity (any role).
Example request
curl https://offers.spoonity.com/v1/admin/promotion-policy \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
Before any save:
{
"policy": {
"vendor_id": "dev-vendor",
"version": 0,
"updated_at": 0,
"max_applied_offers": 5,
"order_percent_mode": "cascade",
"min_spend_basis": "subtotal",
"local_discount_policy": "respect"
},
"saved": false
}
Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid credential |
PUT /v1/admin/promotion-policy
Replace the vendor's policy.
Auth: Vendor API key, or OIDC service identity with admin or editor.
Request body
The settings in the table above, plus expected_version: 0 for the first
save, otherwise the version you read. Unknown keys, including the
read-only record fields, are a 400.
Example request
curl -X PUT https://offers.spoonity.com/v1/admin/promotion-policy \
-H "X-API-Key: YOUR_OFFERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expected_version": 0,
"max_applied_offers": 3,
"order_percent_mode": "additive",
"max_order_discount_percent": 50,
"excluded": { "categories": ["gift_cards", "alcohol"] },
"min_spend_basis": "eligible",
"local_discount_policy": "respect"
}'
Example response
{
"policy": {
"vendor_id": "dev-vendor",
"version": 1,
"updated_at": 1790764275951,
"max_applied_offers": 3,
"order_percent_mode": "additive",
"min_spend_basis": "eligible",
"local_discount_policy": "respect",
"max_order_discount_percent": 50,
"excluded": { "categories": ["gift_cards", "alcohol"] }
},
"saved": true
}
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | Validation failed |
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 403 | FORBIDDEN | OIDC caller with the viewer role |
| 409 | VERSION_REQUIRED | expected_version missing. Carries the current version |
| 409 | VERSION_CONFLICT | expected_version is stale. Carries version and the stored policy |
GET /v1/admin/promotion-policy/history
Every saved version of the policy, newest first.
Auth: Vendor API key, or OIDC service identity (any role).
Example request
curl https://offers.spoonity.com/v1/admin/promotion-policy/history \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
{
"history": [
{
"version": 1,
"at": 1790764275951,
"policy": {
"vendor_id": "dev-vendor",
"version": 1,
"updated_at": 1790764275951,
"max_applied_offers": 3,
"order_percent_mode": "additive",
"min_spend_basis": "eligible",
"local_discount_policy": "respect",
"max_order_discount_percent": 50,
"excluded": { "categories": ["gift_cards", "alcohol"] }
}
}
]
}
by appears on an entry saved by a named person.
Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid credential |
GET /v1/admin/loyalty-rewards
The vendor's loyalty rewards, read-only, so they can be shown beside the promotions they stack with. They are edited in the loyalty program, not here.
Auth: Vendor API key, or OIDC service identity (any role).
The response has three parts:
rewards: the rewards the engine prices, in the engine's offer shape. These are exactly what arbitration sees. A loyalty reward's discount applies to one line: a percent or amount reward is item-scoped withmax_quantity: 1.unpriced: active loyalty rewards the engine cannot price. They never enter arbitration, and are listed so they are not silently missing. Each has areason:POS_PRICED: no discount definition, and a catalog identifier starting withdiscount_orclover_. The POS prices it by catalog code (Clover, for example, rings it as 100% off the line the cashier picks), which the engine cannot do because it cannot pick the line.NO_DISCOUNT_DEFINITION: no discount definition and any other identifier.UNSUPPORTED_DISCOUNT: a discount definition this service cannot read.
loyalty.connected: whether this vendor's loyalty program is connected to Offers. A vendor without a connection gets200with empty lists andconnected: false; that is not an error.
Inactive rewards, Loyalty Pay (a tender, not a discount) and information-only rows appear in neither list.
unpriced entries:
| Field | Type | Description |
|---|---|---|
vendor_perk_redemption_id | integer | The reward's id in the loyalty program |
name | string | Reward name |
catalog_identifier | string | The loyalty catalog identifier (the POS code), when the reward has one |
pos_reference | string | discount_<identifier>, with the identifier exactly as the loyalty program sends it, and not doubled when it already starts with discount_ |
cost_points | integer | Point cost, when the reward has one |
pos_ids | string[] | POS ids, ascending, when the reward's data is keyed by point of sale |
reason | string | POS_PRICED, NO_DISCOUNT_DEFINITION or UNSUPPORTED_DISCOUNT |
Example request
curl https://offers.spoonity.com/v1/admin/loyalty-rewards \
-H "X-API-Key: YOUR_OFFERS_API_KEY"
Example response
A connected vendor with one priced reward and two the engine cannot price:
{
"rewards": [
{
"offer_id": "off_r12617",
"version": 1,
"name": "New Member Half Off",
"source": { "type": "redemption", "vendor_perk_redemption_id": 12617 },
"pos_reference": "discount_16ozHalfOffEspresso",
"effect": { "type": "percent_off", "scope": "item", "percent": 50, "max_quantity": 1 },
"stacking": { "exclusive": false, "priority": 0 },
"cost_points": 100
}
],
"unpriced": [
{
"vendor_perk_redemption_id": 1644,
"name": "Welcome Reward",
"catalog_identifier": "discount_reward300",
"pos_reference": "discount_reward300",
"cost_points": 30000,
"reason": "POS_PRICED"
},
{
"vendor_perk_redemption_id": 8346,
"name": "Drip Tea",
"catalog_identifier": "DripTea",
"pos_reference": "discount_DripTea",
"cost_points": 5000,
"reason": "NO_DISCOUNT_DEFINITION"
}
],
"loyalty": { "connected": true }
}
Not connected:
{ "rewards": [], "unpriced": [], "loyalty": { "connected": false } }
Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 503 | OFFERS_UNAVAILABLE | Connected, but the loyalty platform failed (error or timeout). Retryable |
Loyalty order outbox
When Spoonity forwards closed POS checks to the loyalty program, each close
(and each void of a closed check) is a row in an outbox that a background
worker posts to the merchant's loyalty platform. These two admin endpoints
show the rows and revive failed ones. They need an API key like the other
/v1/admin/* routes, and they only ever show the key's own vendor.
GET /v1/admin/loyalty-outbox
Newest rows first.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
state | string | pending, sent, dead or skipped | |
limit | integer | 1 to 200. Default 50 |
Any other parameter is a 400.
States:
pending: waiting to be sent, or waiting to be retried.sent: the loyalty platform accepted it.dead: not retried automatically. A 4xx answer, a business error in the platform's answer, 8 failed attempts, or a void whose order is dead.skipped: recorded and never sent (skip_reason):NO_CUSTOMER(a guest),CHECK_VOIDED,FORWARD_DISABLED,NO_LOYALTY_KEYorORDER_SKIPPED(a void whose order was skipped).
Example request
curl "https://offers.spoonity.com/v1/admin/loyalty-outbox?state=dead&limit=20" \
-H "X-API-Key: YOUR_API_KEY"
Example response
{
"items": [
{
"id": "lob_0c1d2e3f",
"vendor_id": "2112901",
"kind": "order",
"dedupe_key": "order:2112901:20261103-104202:1042-20261103-104202",
"receipt_number": "2112901-20261103-104202",
"store_id": "2112901",
"check_id": "20261103-104202",
"pos_transaction_id": "1042-20261103-104202",
"body": { "receipt_number": "2112901-20261103-104202", "card_number": "6040123412341234", "subtotal": 13.98, "total": 6.07 },
"state": "dead",
"attempts": 8,
"next_attempt_at": 1793712970000,
"last_error": "loyalty-api answered 503",
"last_status": 503,
"created_at": 1793712970000,
"updated_at": 1793716570000
}
]
}
body is the request sent to the loyalty platform (shortened here). Times
are epoch milliseconds.
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | A bad query parameter |
| 401 | UNAUTHORIZED | Missing or invalid credential |
POST /v1/admin/loyalty-outbox/{id}/retry
Move a dead row back to pending, with its attempts reset and due now.
Retrying an order also revives the voids that died only because that order
was dead. Needs the admin role; a read-only role cannot retry.
Example request
curl -X POST https://offers.spoonity.com/v1/admin/loyalty-outbox/lob_0c1d2e3f/retry \
-H "X-API-Key: YOUR_API_KEY"
The response is { "item": { ... } } with the row as above and state: "pending", plus revived_voids (a list of row ids) when voids were revived.
Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 403 | FORBIDDEN | Read-only role |
| 404 | NOT_FOUND | No such row for this vendor |
| 409 | NOT_RETRYABLE | The row is not dead. state says what it is |
A row whose loyalty-api key was revoked dies with a last_error that starts
with KEY_REVOKED. Retrying it only helps once the key is restored (below)
or replaced. A row sent with a store's own key carries key_hash, the
SHA-256 of that key (never the key).
POS keys
The store keys Offers has learned from POS traffic, and the keys the
loyalty program has stopped accepting. Admin role only (a viewer or
editor role is 403), and only ever the authenticated merchant's keys.
The key itself is never returned: a key is named by the first 12 hex
characters of its SHA-256.
A key is revoked when any loyalty program call made with it answers that
the key is unknown, not active, expired or that its vendor is not active.
Network errors, timeouts and other errors never revoke a key. A revoked
store key is refused (401 on the POS API) and its stored copy is deleted.
A revoked merchant key from Spoonity's configuration is refused too, and
the merchant's loyalty rewards are unavailable until Spoonity replaces it
in its configuration (an alert fires).
GET /v1/admin/pos-keys
Newest first.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | 1 to 200. Default 50 |
Example request
curl "https://offers.spoonity.com/v1/admin/pos-keys" \
-H "X-API-Key: YOUR_API_KEY"
Example response
{
"items": [
{
"key_hash_prefix": "3f9a1c0b7d2e",
"kind": "learned",
"store_vendor_id": "2112905",
"master_vendor_id": "2112901",
"status": "revoked",
"revoked_reason": "KEY_NOT_ACTIVE",
"first_seen_at": "2026-11-03T08:00:04.120Z",
"last_seen_at": "2026-11-05T21:14:40.002Z",
"last_validated_at": "2026-11-05T08:00:11.734Z"
}
]
}
kind is learned (a store key) or configured (a merchant key from
Spoonity's configuration). status is active or revoked.
revoked_reason is KEY_UNKNOWN, KEY_NOT_ACTIVE, KEY_NOT_FOUND or
VENDOR_NOT_ACTIVE. Active store keys are checked again with the loyalty
program every 24 hours.
POST /v1/admin/pos-keys/{hash}/restore
Check a revoked key with the loyalty program now, and accept it again if
the program does. {hash} is the key_hash_prefix from the listing (or
more of the hash).
- A merchant key: checked with the key from Spoonity's configuration.
- A store key: its stored copy was deleted when it was revoked. Send the key
in the body,
{ "key": "..." }, to check it now. Without a body the revocation is cleared and the key is checked again, like a new key, on its next POS request (status: "cleared").
Example request
curl -X POST https://offers.spoonity.com/v1/admin/pos-keys/3f9a1c0b7d2e/restore \
-H "X-API-Key: YOUR_API_KEY"
Example response
{
"status": "cleared",
"item": {
"key_hash_prefix": "3f9a1c0b7d2e",
"kind": "learned",
"store_vendor_id": "2112905",
"master_vendor_id": "2112901",
"status": "revoked",
"revoked_reason": "KEY_NOT_ACTIVE",
"first_seen_at": "2026-11-03T08:00:04.120Z",
"last_seen_at": "2026-11-05T21:14:40.002Z",
"last_validated_at": "2026-11-05T08:00:11.734Z"
}
}
status is restored (checked and accepted again) or cleared.
Errors
| Status | Code | When |
|---|---|---|
| 400 | KEY_MISMATCH | The key sent does not match the hash |
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 403 | FORBIDDEN | Not the admin role |
| 404 | NOT_FOUND | No such key for this merchant |
| 409 | AMBIGUOUS | More than one key starts with this prefix |
| 409 | NOT_REVOKED | The key is not revoked |
| 409 | STILL_REJECTED | The loyalty program still does not accept the key. reason says why |
| 409 | FOREIGN_MASTER | The key belongs to another merchant |
| 503 | UPSTREAM_UNAVAILABLE | The loyalty program could not be reached. Retry |
POS check API
For a POS that sends the whole check at pay time and wants the discount
back. The customer's app QR, a customer id or phone number, or a coupon code
can go on the check. Spoonity reprices it with the vendor's promotions,
rewards and policy, holds single-use rewards for 15 minutes, and returns one
subtotal discount plus the per-line detail. The POS applies it, takes
payment, and posts close.
- Pay pressed:
POST /partners/pos/checkwith the full check. Send it again if the cart changes; each call replaces the hold. - Apply
subtotal_discountas one subtotal discount, or eachdiscounts[]entry on its line. Take payment. - Check closed:
POST /partners/pos/close, always, even whencheckfailed or timed out. - Refund or void:
POST /partners/pos/void.
Optionally, GET /partners/pos/offers fills a cashier prompt after a scan.
Base path: https://offers.spoonity.com/partners/pos
Version: every response carries X-Spoonity-Api-Version: 2026-10-16.
New request fields are always optional and new response fields can be
ignored; nothing documented is removed or changes meaning without a new
version.
Evaluation ids
The engine keys a check as "<store>:<check_id>", the store being the POS
key's, for example S12:1042. That is why neither id may contain a colon. You never send it
back; it is returned for support and logs.
If a check's hold expires, or it is voided while still open, a later check
reserves under a new id with a generation suffix: S12:1042:2, then
S12:1042:3. Every later call on that check finds the current one. A check
has 10 ids in total. Each expiry, open void and lost race for a single-use
reward uses one; after that check answers 409 CHECK_REOPEN_LIMIT.
Idempotency
checkis safe to repeat: the samecheck_idfrom the same store's key always refers to the same hold, replaced with the new cart's result. A re-check that no longer qualifies releases the held reward.closeis idempotent onpos_transaction_idwithin a check: a retry returns the same answer and never commits twice. Transaction ids only need to be unique per check.voidis idempotent onpos_transaction_id, tracked separately fromclose, so a void may reuse the close's transaction id.- A closed check cannot be checked again (
409 CHECK_CLOSED); a new sale needs a newcheck_id.
Timeouts and retries
- Time out
checkat about 3 seconds. On a timeout, a5xxor a network error, close the check without a Spoonity discount. Do not block the cashier. - Retry
closeandvoidon5xxor network errors, with backoff. They are idempotent. - Do not retry a
4xx. The one exception is409 OFFERS_RESERVED: another check won the race for the same single-use reward three times inside this one request. Re-sendcheckonce, and if it fails again, proceed without a discount. 503 OFFERS_UNAVAILABLEoncheck, including a member lookup that failed, means proceed without a discount. Alwaysclose.
customer_code (the scanned card number; the simple form of customer.customer_id) and phone resolve a member only
for a merchant whose loyalty program is connected to Offers; otherwise the
check is priced with the promotions open to everyone (customer: null).
A reward the customer picked in the app is applied from the scanned
customer_code alone (see App reward picks); the POS
does not send its offer_id.
Code prefix. A POS that recognises loyalty codes by a fixed prefix sends
the whole code as scanned, prefix included; Spoonity removes the prefix. The
prefix is set per merchant during setup and matched exactly, letter case
included; a code that does not start with the whole prefix is used as sent.
It is removed from customer_code, customer.customer_id and customer.phone on check
and close, and from codes the app registers (code on POST /partners/app/selections, PUT /partners/app/code).
POST /partners/pos/check
Reprice a check and hold its single-use rewards.
Auth: Authorization: Bearer POS key (or X-Spoonity-POS-Key).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
check_id | string | Yes | Your check number. A-Z a-z 0-9 _ . -, at most 60 characters, no colon. Must stay unique per store for as long as the check can be refunded; prefix a daily-reset number with the business date |
lines | array | Yes | Up to 200 lines, see below |
customer_code | string | The scanned card number, 1 to 128 characters. The simple form of customer: { "customer_id": ... }, with identical behaviour. Send customer_code or customer, not both (400 INVALID_REQUEST). Omit both for a guest | |
customer | object | The alternative to customer_code: exactly one of customer_id (the scanned card number, 1 to 128 characters), phone (3 to 32 characters) or qr_token (1 to 512 characters; not available yet, answers 503 CUSTOMER_LOOKUP_UNAVAILABLE). Omit for a guest | |
codes | string[] | Coupon or promo codes. At most 50 | |
selected_offer_ids | string[] | The offer_id of each reward or promotion the customer wants to use. At most 50 | |
channel | string | Default pos. Free-form; recommended pos, dine_in, takeout, drive_thru, delivery, kiosk. Promotions can be limited to channels | |
discounts | array | Discounts the POS already took off the whole check: { id, name?, amount }, cents. At most 50. They lock no line | |
subtotal | integer cents | The POS's own subtotal for the check: the sum of its items and modifiers before any discount and before tax, in integer cents. Spoonity still prices from lines and never from this number. It is a cross-check: when it differs from the subtotal Spoonity computes, the response carries subtotal_mismatch, which catches mapping mistakes such as modifiers counted twice or a missing line. A mismatch is never an error. | |
cashier | object | { id, name? }, each 1 to 50 characters. Logged | |
metadata | object | Your own fields, ignored by pricing. String keys 1 to 64 characters; values a string up to 256, a number, a boolean or null; at most 50 keys | |
terminal_id | string | Logged only | |
pos_transaction_id | string | Logged only on check |
A line is { line_id, sku, name?, price, quantity, categories?, modifiers?, discounts?, components?, metadata? }.
price is the unit price in cents. If the POS prices modifiers separately, send the base price and list the modifiers; if it rolls them into the item price, send the full price and no modifiers. A modifier is
{ id, name?, price, quantity, modifiers?, metadata? }, quantity per unit
of the line; its own modifiers (up to 3 levels deep) have quantity per
unit of their parent, and every level is priced. discounts are
discounts the POS already applied to the line: { id, name?, amount, source? },
whole-line cents. Up to 50 categories and 50 discounts per line, and 50
modifiers per line (per component on a combo) counting every level. Unknown
fields anywhere except inside metadata are a 400.
Combos. Send a combo as one line whose price is the combo price,
with its parts in components: [{ component_id, sku, name?, price, quantity, categories?, modifiers?, metadata? }]. A part's price is its a la carte
unit price; it is not charged, it only decides how Spoonity splits the
combo price across the parts (the parts always add up to the combo price).
quantity is per combo. Modifiers go on the part, never on the combo line.
A discount on a part takes off at most that part's share of the combo
price. component_id is unique within the combo, and every part unit
counts toward the 2000-unit budget.
Example request
A customer identified by id, a coupon code, and a cookie the register has already discounted:
curl -X POST https://offers.spoonity.com/partners/pos/check \
-H "Authorization: Bearer YOUR_POS_KEY" \
-H "Content-Type: application/json" \
-d '{
"check_id": "1042",
"terminal_id": "T1",
"customer_code": "cust_1001",
"codes": ["WELCOME3"],
"selected_offer_ids": ["reward_free_cookie"],
"lines": [
{ "line_id": "1", "sku": "burger", "name": "Classic Burger", "price": 899, "quantity": 1,
"categories": [{ "id": "mains" }] },
{ "line_id": "2", "sku": "cola", "name": "Cola", "price": 279, "quantity": 1,
"categories": [{ "id": "drinks" }],
"modifiers": [{ "id": "large", "name": "Large", "price": 50, "quantity": 1 }] },
{ "line_id": "3", "sku": "cookie", "name": "Cookie", "price": 199, "quantity": 1,
"categories": [{ "id": "desserts" }],
"discounts": [{ "id": "emp", "name": "Employee 50%", "amount": 100 }] }
]
}'
Example response
200. The code applied. The cookie reward was skipped because the register
had already discounted that line (LOCALLY_DISCOUNTED).
{
"evaluation_id": "S12:1042",
"check_id": "1042",
"customer": {
"customer_id": "cust_1001",
"balances": [{ "currency_id": "points", "balance": 420 }]
},
"subtotal": 1427,
"subtotal_discount": 300,
"external_discount_total": 100,
"total": 1027,
"discounts": [
{ "pos_reference": "discount_promo_WELCOME3", "offer_id": "promo_WELCOME3",
"name": "$3 Off with Code WELCOME3", "amount": 300, "scope": "order",
"allocations": [
{ "line_id": "1", "amount": 203, "unit_amount": 203 },
{ "line_id": "2", "amount": 74, "unit_amount": 74 },
{ "line_id": "3", "amount": 23, "unit_amount": 23 }
] }
],
"offers": [
{ "offer_id": "reward_free_cookie", "name": "Free Cookie (150 pts)", "status": "skipped",
"source": { "type": "redemption", "vendor_perk_redemption_id": 501 },
"pos_reference": "discount_free_cookie", "cost_points": 150,
"reason": { "code": "LOCALLY_DISCOUNTED", "message": "Eligible items already carry a discount from the register" } },
{ "offer_id": "promo_WELCOME3", "name": "$3 Off with Code WELCOME3", "status": "applied",
"source": { "type": "promotion_code", "code": "WELCOME3" },
"pos_reference": "discount_promo_WELCOME3", "funding": "restaurant", "discount_total": 300 },
{ "offer_id": "promo_SPEND20", "name": "Spend more, save more", "status": "inapplicable",
"source": { "type": "promotion_code" }, "pos_reference": "discount_promo_SPEND20",
"reason": { "code": "TIER_NOT_REACHED", "message": "Spend $20.00 to unlock", "next_min_spend": 2000, "shortfall": 673 } },
{ "offer_id": "promo_LUNCHCOMBO", "name": "Lunch combo $10.99", "status": "applicable",
"source": { "type": "promotion_code" }, "pos_reference": "discount_promo_LUNCHCOMBO",
"reason": { "code": "BUNDLE_INCOMPLETE", "message": "Add the remaining items to complete this combo",
"missing": [{ "component": 1, "required": 1, "available": 0 }] } }
],
"receipt_lines": ["$3 Off with Code WELCOME3 applied, you saved $3.00"],
"redemption_id": "ored_d768ed3c-503c-453f-a03c-70ae6538695c",
"hold_expires_at": "2026-09-30T10:46:31.864Z"
}
subtotal_discountis the whole Spoonity discount, item and order combined. A POS that takes one number applies it as a subtotal discount.discounts[]sums tosubtotal_discount.scope: "item"entries carryline_id(andcomponent_idfor a part of a combo,unit_index,quantity);scope: "order"entries carryallocations, their split by line (and part), which add up to the entry'samount. Echo the ones you applied onclose.amount(on an entry or an allocation) is the total for the units it covers: apply it once.unit_amountis that total divided by the units covered (an item entry'squantity; every unit of the line or part for an allocation), present only when it divides evenly. A POS that multiplies an item modifier by the line quantity appliesunit_amountinstead, or sends units that get different discounts as separate lines.totalissubtotalminusexternal_discount_totalminussubtotal_discount, pre-tax.external_discount_totalappears only when lines or the check carried POS discounts.subtotal_mismatch({ received, computed }, cents) appears only when the request carriedsubtotaland it differs fromsubtotal. Pricing is unchanged and the status is still 200. Absent when they agree.receipt_linesare display text; the wording can change (the engine separates the two halves with a dash character).customerisnullfor a guest, and for a member the merchant's loyalty program could not match (the check is then priced as a guest). For a member,balancesholds one entry per loyalty currency, keyed by its currency id, in hundredths.hold_expires_at: single-use rewards are held until then. Acloseafter it does not commit (EVALUATION_EXPIRED); sendcheckagain first if a check sits that long.
Errors
| Status | Code | When | POS action |
|---|---|---|---|
| 400 | INVALID_REQUEST | Validation failed: decimals, duplicate line_id, unknown fields, a colon in an id, two customer identifiers (including customer_code with customer), any limit | Fix the integration; do not retry |
| 401 | UNAUTHORIZED | Missing or unknown POS key, or one the loyalty program no longer accepts | Proceed without discount |
| 413 | PAYLOAD_TOO_LARGE | The body is over 256 KB | Fix the integration; proceed without discount |
| 429 | RATE_LIMITED | Too many requests for this key. Retry-After gives the seconds to wait | Wait that long and retry; if it does not clear, proceed without discount |
| 409 | CHECK_CLOSED | The check already closed or was refunded. Carries state and evaluation_id | New sale, new check_id |
| 409 | CHECK_REOPEN_LIMIT | All 10 evaluation ids used | New check_id |
| 409 | OFFERS_RESERVED | Lost the race for a single-use reward three times | Re-send once, else proceed without discount |
| 503 | OFFERS_UNAVAILABLE | Promotions, policy or database could not be read, or a member lookup failed | Proceed without discount; always close |
| 503 | CUSTOMER_LOOKUP_UNAVAILABLE | A customer.qr_token could not be resolved (not available yet) | Proceed without discount; always close |
| 500 | INTERNAL | A bug on Spoonity's side | As for 503 |
{ "error": { "code": "CHECK_CLOSED", "message": "This check is already closed; a new sale needs a new check_id", "state": "committed", "evaluation_id": "S12:1042" } }
POST /partners/pos/close
Commit a closed check. Send it once the check is paid, always.
Auth: Authorization: Bearer POS key (or X-Spoonity-POS-Key).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
check_id | string | Yes | As on check |
pos_transaction_id | string | Yes | Your id for this closed transaction. The idempotency key |
receipt.discounts | array | Yes | The Spoonity discounts you actually applied, echoed from check: { pos_reference, amount, name?, line_id?, component_id?, unit_amount? } (unit_amount is accepted and ignored). Empty if none. Up to 200 |
receipt.lines | array | Yes | The final lines, same shape and limits as on check. Posted to the loyalty program for points when the forward is on |
receipt.total | integer cents | Yes | The receipt total before tax, after every discount. Posted to the loyalty program |
receipt.pos_discounts | array | Your own check-level discounts as applied, { id, name?, amount }. At most 50. Recorded | |
receipt.taxes | array | The taxes on the check, one entry per tax: [{ id, name?, amount }]. id is 1 to 64 characters and unique within the array, name up to 256 characters, amount integer cents, 0 or more. At most 20. Each entry is posted to the loyalty program as a tax of the sale; an id the loyalty program does not know is still recorded. There is no single receipt.tax field: sending one is a 400. | |
receipt.tip | integer cents | Recorded; not posted (the loyalty program has no field for it) | |
receipt.payments | array | { method, amount }, method 1 to 64 characters, at most 50. Recorded; not posted (no field for it) | |
receipt.metadata, metadata | object | Your own fields, as on check | |
cashier | object | { id, name? }, each 1 to 50 characters. The cashier of the sale in the loyalty program (name defaults to the id); absent, the sale names Spoonity Offers | |
customer_code | string | As on check: the scanned card number, the simple form of customer: { "customer_id": ... }. Send customer_code or customer, not both | |
customer | object | The alternative to customer_code, as on check: exactly one of customer_id, phone, qr_token. Names the customer the sale is posted to the loyalty program for when no earlier check for this check identified one; when both did, the one from check is used. Never changes the discounts or the commit. A qr_token here names no one | |
terminal_id | string | When it is 1 to 9 digits, the till number in the loyalty program; otherwise till 0 | |
closed_at | ISO 8601 with offset | When the check closed. The 15-minute hold is judged at this time when it is within 24 hours back and 5 minutes ahead of Spoonity's clock (else the arrival time). Its local wall clock dates the sale in the loyalty program; a Z time does not |
Spoonity commits what the last check evaluated; it does not reprice at
close. The references and the sum of receipt.discounts[].amount are
compared with that result.
Example request
curl -X POST https://offers.spoonity.com/partners/pos/close \
-H "Authorization: Bearer YOUR_POS_KEY" \
-H "Content-Type: application/json" \
-d '{
"check_id": "1042",
"pos_transaction_id": "TXN-S12-1042",
"terminal_id": "T1",
"closed_at": "2026-09-30T12:31:05-04:00",
"receipt": {
"lines": [
{ "line_id": "1", "sku": "burger", "name": "Classic Burger", "price": 899, "quantity": 1,
"categories": [{ "id": "mains" }] },
{ "line_id": "2", "sku": "cola", "name": "Cola", "price": 279, "quantity": 1,
"categories": [{ "id": "drinks" }],
"modifiers": [{ "id": "large", "name": "Large", "price": 50, "quantity": 1 }] },
{ "line_id": "3", "sku": "cookie", "name": "Cookie", "price": 199, "quantity": 1,
"categories": [{ "id": "desserts" }],
"discounts": [{ "id": "emp", "name": "Employee 50%", "amount": 100 }] }
],
"discounts": [{ "pos_reference": "discount_promo_WELCOME3", "amount": 300 }],
"total": 1027
}
}'
Example response
{ "committed": true, "redemption_id": "ored_d768ed3c-503c-453f-a03c-70ae6538695c", "evaluation_id": "S12:1042" }
If what you applied differs from what check returned, Spoonity still
commits (the money has left the till) and reports the difference:
{
"committed": true,
"redemption_id": "ored_dbde8782-27cb-42ed-b2be-42b2d90f12ef",
"evaluation_id": "S12:1043",
"mismatch": {
"expected_pos_references": ["discount_promo_WELCOME3"],
"received_pos_references": ["discount_promo_WELCOME3"],
"expected_discount_total": 300,
"received_discount_total": 250
}
}
committed: false is still a 200, so the POS never retries it forever.
reason says why:
reason | Meaning |
|---|---|
NO_PENDING_EVALUATION | Spoonity never saw a check for this check. Nothing to commit. Body: { "committed": false, "redemption_id": null, "reason": "NO_PENDING_EVALUATION" }. The sale is still posted for points when the close carries customer_code or customer |
EVALUATION_EXPIRED | The 15-minute hold had lapsed. The reward was not consumed |
EVALUATION_CANCELLED | The check was voided while open, or the last check answered 409 OFFERS_RESERVED |
EVALUATION_ROLLED_BACK | The transaction was already voided |
Apart from NO_PENDING_EVALUATION, the body also carries redemption_id,
evaluation_id and state.
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | Validation failed |
| 401 | UNAUTHORIZED | Missing or unknown POS key, or one the loyalty program no longer accepts |
| 413 | PAYLOAD_TOO_LARGE | The body is over 256 KB |
| 429 | RATE_LIMITED | Too many requests for this key. See Retry-After |
| 503 | OFFERS_UNAVAILABLE | The database could not be reached. Retry with backoff |
POST /partners/pos/void
Void or refund a closed check, or cancel an open one. Restores single-use rewards, usage counts and budget.
Auth: Authorization: Bearer POS key (or X-Spoonity-POS-Key).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
check_id | string | Yes | As on check |
pos_transaction_id | string | Yes | Idempotency key for the void |
terminal_id | string | Logged only |
Partial refunds are not supported on this surface.
Example request
curl -X POST https://offers.spoonity.com/partners/pos/void \
-H "Authorization: Bearer YOUR_POS_KEY" \
-H "Content-Type: application/json" \
-d '{ "check_id": "1042", "pos_transaction_id": "TXN-S12-1042" }'
Example response
{ "voided": true, "redemption_id": "ored_d768ed3c-503c-453f-a03c-70ae6538695c", "evaluation_id": "S12:1042", "state": "rolled_back" }
voided: true means nothing is held or consumed for the check any more.
state is rolled_back (it had closed), cancelled (it was open) or
expired (its hold had already lapsed). An unknown check answers
{ "voided": false, "redemption_id": null, "reason": "NO_PENDING_EVALUATION" }.
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | Validation failed |
| 401 | UNAUTHORIZED | Missing or unknown POS key, or one the loyalty program no longer accepts |
| 413 | PAYLOAD_TOO_LARGE | The body is over 256 KB |
| 429 | RATE_LIMITED | Too many requests for this key. See Retry-After |
| 503 | OFFERS_UNAVAILABLE | The database could not be reached. Retry with backoff |
GET /partners/pos/offers
The promotions open to everyone at a store, for a cashier prompt before the cart is final. Nothing is applied or held. Looking up a member's offers here is not available yet.
Auth: Authorization: Bearer POS key (or X-Spoonity-POS-Key).
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
channel | string | Default pos | |
customer | string | A customer app QR token, 1 to 512 characters. Not available yet: answers 503 CUSTOMER_LOOKUP_UNAVAILABLE |
Any other query parameter is a 400. Code-gated offers are never listed.
Offers outside their schedule are left out. An offer whose cart condition
is not met yet carries needs, a reason with the shortfall.
Example request
curl "https://offers.spoonity.com/partners/pos/offers" \
-H "Authorization: Bearer YOUR_POS_KEY"
Example response
A guest, with an empty cart:
{
"customer": null,
"offers": [
{
"offer_id": "promo_SPEND20",
"name": "Spend more, save more",
"pos_reference": "discount_promo_SPEND20",
"effect_type": "tiered",
"auto_apply": false,
"pre_selected": false,
"needs": { "code": "TIER_NOT_REACHED", "message": "Spend $20.00 to unlock", "next_min_spend": 2000, "shortfall": 2000 }
},
{
"offer_id": "promo_LUNCHCOMBO",
"name": "Lunch combo $10.99",
"pos_reference": "discount_promo_LUNCHCOMBO",
"effect_type": "bundle",
"auto_apply": false,
"pre_selected": false,
"needs": {
"code": "BUNDLE_INCOMPLETE",
"message": "Add the remaining items to complete this combo",
"missing": [
{ "component": 0, "required": 1, "available": 0 },
{ "component": 1, "required": 1, "available": 0 },
{ "component": 2, "required": 1, "available": 0 }
]
}
}
]
}
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | An unknown parameter |
| 401 | UNAUTHORIZED | Missing or unknown POS key, or one the loyalty program no longer accepts |
| 413 | PAYLOAD_TOO_LARGE | The body is over 256 KB |
| 429 | RATE_LIMITED | Too many requests for this key. See Retry-After |
| 503 | OFFERS_UNAVAILABLE | Promotions or policy could not be read |
| 503 | CUSTOMER_LOOKUP_UNAVAILABLE | The customer token could not be resolved |
POS Quick Pay pass-through
Pay with a customer's app balance from the POS. These routes forward to Spoonity's loyalty platform and return its HTTP status and body unchanged. Offers implements no Quick Pay rules: no sign check, no balance check, no idempotency and no error mapping. Nothing is written to Offers' database.
Auth: Authorization: Bearer POS key (or X-Spoonity-POS-Key). The key
is the store's Spoonity API key and is passed on to the loyalty platform; a
key that is not one answers 401 UNAUTHORIZED. Same rate limit, body limit
and X-Spoonity-Api-Version header as the other POS routes.
POST /partners/pos/quickpay/order
Forwarded as POST /order. Redeem (negative amount) or load (positive).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
card_number | string | Yes | The scanned code, prefix included. Offers removes the merchant's code prefix |
amount | integer | Yes | Signed cents: positive loads, negative redeems. Sent on as decimal dollars (-1250 becomes -12.5) |
till | integer | Required by the loyalty platform | |
receipt_number | string | Required by the loyalty platform. Unique per attempt | |
cashier | object | { id, name } |
Any other field is passed on unchanged. Offers rejects only an amount that
is not an integer and a card_number that is not a non-empty string (400).
Example request
curl -X POST https://offers.spoonity.com/partners/pos/quickpay/order \
-H "Authorization: Bearer YOUR_POS_KEY" \
-H "Content-Type: application/json" \
-d '{ "card_number": "SPN123456789", "amount": -1250, "till": 2, "receipt_number": "S12-1042-1", "cashier": { "id": 17, "name": "Dana" } }'
Example response
The loyalty platform's reply. A refusal is HTTP 200 with success: false and
the cause in error.errors[]. Balances are in dollars.
{
"success": true,
"reference_number": "303188170",
"receipt_data": {
"lines": ["Successfully redeemed 12.50 quick pay balance"],
"outstanding": 0,
"user": { "id": "22293026", "card_number": "123456789", "balances": [{ "id": 9559, "currency": "Canadian Dollar", "balance": 37.5, "type": "Quick Pay" }] }
},
"error": { "errors": [], "code": null, "reference_id": null }
}
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | amount is not an integer, or card_number is missing or empty |
| 401 | UNAUTHORIZED | Missing or unknown POS key, or a key that is not a Spoonity API key |
| 503 | QUICKPAY_UNAVAILABLE | The loyalty platform did not answer within 8 seconds, or could not be reached |
Every other status and body is the loyalty platform's.
GET /partners/pos/quickpay/balance
Forwarded as GET /quick-pay. Query: card_number (required, prefix
included). Same reply shape as order; receipt_data.user.balances[] holds
the balance in dollars.
curl "https://offers.spoonity.com/partners/pos/quickpay/balance?card_number=SPN123456789" \
-H "Authorization: Bearer YOUR_POS_KEY"
POST /partners/pos/quickpay/void
Forwarded as POST /order/void, body unchanged. Send the reference_number
of a load's reply as receipt, as a number. The loyalty platform voids only
the customer's most recent Quick Pay receipt and does not void a redemption;
reverse a redemption by loading the same amount back.
curl -X POST https://offers.spoonity.com/partners/pos/quickpay/void \
-H "Authorization: Bearer YOUR_POS_KEY" \
-H "Content-Type: application/json" \
-d '{ "receipt": 303188169 }'
A successful reply is { "voided": true }.
App reward picks API
For a merchant's mobile app. The customer picks a reward in the app before the till; when the cashier scans their code, the POS check applies it. See the app reward picks guide for the flow.
Base path: https://offers.spoonity.com/partners/app
Auth: Authorization: Bearer customer session key and
X-Spoonity-Vendor, see Customer session.
POST /partners/app/selections
Pick a reward for today.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
reward_id | integer | One of the two | The loyalty reward id (vendor_perk_redemption_id). Maps to offer off_r<reward_id> |
offer_id | string | One of the two | The offer id |
Send exactly one. Unknown fields are a 400.
Example request
curl -X POST https://offers.spoonity.com/partners/app/selections \
-H "Authorization: Bearer CUSTOMER_SESSION_KEY" \
-H "X-Spoonity-Vendor: 2112901" \
-H "Content-Type: application/json" \
-d '{ "reward_id": 501 }'
Example response
201 for a new pick, 200 when the reward was already picked today.
{
"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"
}
}
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | Validation failed, including both or neither of reward_id and offer_id |
| 401 | UNAUTHORIZED | Header missing, session invalid, vendor not set up, or no loyalty account |
| 409 | OFFER_NOT_AVAILABLE | The customer cannot have the reward now. error.reason is { code, message }, a code from Reason codes or OFFER_NOT_FOUND |
| 409 | TOO_MANY_SELECTIONS | 10 open picks today already |
| 413 | PAYLOAD_TOO_LARGE | The body is over 256 KB |
| 429 | RATE_LIMITED | Too many requests. See Retry-After |
| 503 | LOYALTY_UNAVAILABLE | The merchant's loyalty host could not be reached |
GET /partners/app/selections
Today's picks that can still apply, oldest first, as { "selections": [...] }
with the same fields as above. state is open (waiting for the till) or
pending (a POS check holds it until the check closes, at most 15
minutes). Used, cancelled and expired picks are not listed.
Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Header missing, session invalid, vendor not set up, or no loyalty account |
| 429 | RATE_LIMITED | Too many requests. See Retry-After |
| 503 | LOYALTY_UNAVAILABLE | The merchant's loyalty host could not be reached |
DELETE /partners/app/selections/{selection_id}
Take a pick back. Answers { "cancelled": true }, and the same again when
repeated.
Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Header missing, session invalid, vendor not set up, or no loyalty account |
| 404 | NOT_FOUND | No such pick for this customer |
| 409 | SELECTION_USED | The check that applied it has closed |
| 429 | RATE_LIMITED | Too many requests. See Retry-After |
| 503 | LOYALTY_UNAVAILABLE | The merchant's loyalty host could not be reached |
Reason codes
reason.code on an offer result (needs.code on the POS cashier prompt).
The status column is where the code is normally seen. Extra fields are
machine-readable context next to code and message.
| Code | Status | Meaning | Extra fields |
|---|---|---|---|
MIN_SPEND_NOT_MET | inapplicable | Subtotal below min_spend | shortfall (cents); basis: "eligible" when the policy uses the eligible subtotal |
NO_ELIGIBLE_ITEMS | applicable | A free item offer whose SKU is not in the cart. The offer also carries add_item_hint: { sku } | |
OUTSIDE_ACTIVE_WINDOW | inapplicable | Before active.start or after active.end | |
OUTSIDE_DAYPART | inapplicable | Outside every daypart | |
TIER_NOT_ELIGIBLE | inapplicable | The customer's loyalty tier is not in tiers | |
INSUFFICIENT_BALANCE | inapplicable | Not enough points for a point-cost reward (a guest has 0) | required, balance |
CODE_REQUIRED | inapplicable | Simulate explain only: a code-gated offer whose code was not entered. Evaluate leaves such offers out | |
CONDITION_NOT_MET | inapplicable | Another condition failed (segment, tag, first order, order count, store, channel condition) | attribute |
STORE_NOT_ELIGIBLE | inapplicable | store_id not in stores | |
CHANNEL_NOT_ELIGIBLE | inapplicable | channel not in channels | |
EXCLUSIVE_CONFLICT | skipped | An exclusive offer applied, or this exclusive offer could not apply alongside those already applied | |
LOWER_VALUE_THAN_APPLIED | Reserved. Not emitted today | ||
UNIT_CONFLICT | skipped | The units it needs already carry another offer's discount | |
MAX_OFFERS_REACHED | skipped | The policy's max_applied_offers was reached | |
ZERO_DISCOUNT | skipped | It would not reduce the total (for example, the order is already fully discounted) | |
ALREADY_USED | inapplicable | A single-use offer this customer already redeemed | |
RESERVED | inapplicable | A single-use offer held by another order in progress | |
CUSTOMER_REQUIRED | inapplicable | The offer needs an identified customer | because: "single_use" when implied by single use or a per-customer cap |
USAGE_LIMIT_REACHED | inapplicable | A usage limit was reached | scope (total, per_customer, per_day), limit, used |
BUDGET_EXHAUSTED | inapplicable | budget_cents is spent | budget_cents, spent_cents |
GROUP_CONFLICT | skipped | Another offer in the same stacking.group applied | group, applied_offer_id |
LOCALLY_DISCOUNTED | skipped | The units it needs carry a POS line discount and the policy is respect. Check-level POS discounts never cause it | |
ORDER_CAP_REACHED | skipped | Trimmed to nothing by max_order_discount_percent | cap |
MIN_QUANTITY_NOT_MET | inapplicable | Fewer eligible units than min_quantity | required, eligible |
TIER_NOT_REACHED | inapplicable | No spend tier reached | next_min_spend, shortfall |
BUNDLE_INCOMPLETE | applicable | The cart does not hold a complete combo set | missing: [{ component, required, available }] |
Rate limits
The partner routes (/partners/pos/* and /partners/app/*) are rate limited
per credential. The default is 20 requests per second sustained, with bursts
of up to 60. A credential that is over the limit gets:
HTTP/1.1 429 Too Many Requests
Retry-After: 1
{ "error": { "code": "RATE_LIMITED", "message": "Too many requests; retry after the Retry-After interval", "retry_after_seconds": 1 } }
Wait Retry-After seconds, then retry. A POS that is still limited after
that closes the check without a discount.
The limit is counted in each running instance of the service, so the
ceiling across the service is a little higher than the figure above. It
protects against a runaway client; it is not a quota. Every route also
refuses a request body over 256 KB with 413 PAYLOAD_TOO_LARGE.
Error codes
Every error on this service, by code. Each endpoint above lists the ones it returns.
| Status | Code | Meaning |
|---|---|---|
| 400 | INVALID_REQUEST | Validation failed. issues[] lists { path, message } |
| 400 | UNKNOWN_LINES | Partial return named lines that are not in the redemption |
| 401 | UNAUTHORIZED | Missing or invalid credential |
| 403 | FORBIDDEN | Read-only role attempted a write |
| 404 | NOT_FOUND | Unknown route, or a resource that does not exist for this vendor |
| 409 | OFFERS_RESERVED | A single-use offer is held by another order |
| 409 | EVALUATION_TERMINAL | The evaluation_id is already finished |
| 409 | VERSION_REQUIRED | An update without expected_version |
| 409 | VERSION_CONFLICT | An update with a stale expected_version |
| 409 | PROMOTION_ARCHIVED | An edit to an archived promotion |
| 409 | PROMOTION_EXISTS | Create with an identifier that is taken |
| 409 | INVALID_STATE | A redemption in the wrong state for the action |
| 409 | CHECK_CLOSED | POS: the check already closed |
| 409 | CHECK_REOPEN_LIMIT | POS: the check has no evaluation ids left |
| 409 | OFFER_NOT_AVAILABLE | App: the customer cannot have the reward now. error.reason says why |
| 409 | TOO_MANY_SELECTIONS | App: 10 open picks today already |
| 409 | SELECTION_USED | App: the pick was used by a check that closed |
| 409 | NOT_RETRYABLE | Loyalty outbox: only a dead row can be retried |
| 413 | PAYLOAD_TOO_LARGE | The request body is over 256 KB. Any route |
| 429 | RATE_LIMITED | Too many requests for this key. Retry-After gives the seconds to wait. POS and app routes |
| 500 | INTERNAL | Unexpected server error |
| 503 | OFFERS_UNAVAILABLE | Catalog, policy, loyalty source or database unavailable. Retryable |
| 503 | CUSTOMER_LOOKUP_UNAVAILABLE | POS: a customer QR token could not be resolved. Retryable |
| 503 | LOYALTY_UNAVAILABLE | App: the merchant's loyalty host could not be reached. Retryable |
| 503 | QUICKPAY_UNAVAILABLE | POS Quick Pay: the loyalty platform could not be reached or took over 8 seconds |
Health
GET /readyz
Readiness. No credential.
Example request
curl https://offers.spoonity.com/readyz
Example response
{ "ready": true, "db": "ok" }
503 { "ready": false, "db": "connecting" } (or "unavailable") while the
database is not answering.
GET /healthz exists in the service but is not usable on
offers.spoonity.com: the hosting frontend answers that path itself with a
404. Use /readyz.
Not on this page
- Partner protocol layers. The service also has translators for specific
partner promotion protocols (Olo, Toast, NCR PES, the Deliverect loyalty
partner and Deliverect Commerce). They are not enabled on
offers.spoonity.comtoday. Some of their routes appear in the OpenAPI spec because the spec is shared with the service repository. - Tax, offline mode and points accrual. The engine is pre-tax, needs a live connection, and does not post points; the loyalty platform does.