Spoonity OffersView as markdown

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:

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.

Surfaces

SurfacePathsWho calls itCredential
Evaluate and lifecycle/v1/evaluate, /v1/offers, /v1/redemptions/*, /v1/locks/*A kiosk, ordering app or channel backend that builds the cart itselfVendor API key
Admin catalog/v1/admin/*A merchant's back office, or PrismVendor API key, or OIDC service identity
POS check/partners/pos/*A POS that sends the whole check at pay timePOS key (Authorization: Bearer)
App reward picks/partners/app/*A merchant's mobile app, so a customer can pick a reward before the tillCustomer session key (Authorization: Bearer) plus X-Spoonity-Vendor
Health/readyzMonitoringNone

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

HeaderRequiredMeaning
Authorization: Bearer <Google ID token>YesToken for an allow-listed service account, with this service as the audience
X-Spoonity-VendorYes, ^[A-Za-z0-9_-]{1,64}$The vendor the call acts for. Missing or malformed is 401
X-Spoonity-UserNo, 1 to 256 printable charactersThe person acting; stamped on created_by / updated_by
X-Spoonity-RoleNoExactly 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

Evaluate and lifecycle

A device that builds its own cart uses this surface. The loop:

  1. Evaluate on every change. Call POST /v1/evaluate whenever the cart or the guest's selection changes. Reuse one evaluation_id for the whole checkout attempt; each call replaces the previous result for that id. Always send the full current cart and selection.
  2. 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 a pending redemption. The response carries redemption_id and lock.
  3. Submit the order. Send order_payload to the loyalty platform unchanged. Its receipt_number is the evaluation_id.
  4. Commit is event-driven. When the order lands, an order.submitted event posted to /webhooks/events turns the pending redemption into committed. 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.
  5. 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

FieldTypeRequiredDescription
evaluation_idstringYesYour id for this checkout attempt. Reuse it on every call for the attempt. Becomes order_payload.receipt_number
cart.line_items[]arrayYes1 to 200 lines, see below
customer.identifierstringLoyalty 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_hashstringAlternative identifier from a POS session
customer.order_countintegerOrders the customer has placed, if you know it. A value the loyalty platform resolves wins
customer.tagsstring[]Customer tags, if you know them. A resolved list wins
codesstring[]Promo codes the guest entered
selectedstring[]Offer ids the guest chose (typically point-cost rewards)
selection_modestringmanual (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_idstringStore, for store-restricted offers
channelstringChannel, for example kiosk, web, pos
lock.ttl_secondsinteger1 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? }:

FieldTypeDescription
line_idstringUnique within the cart
idstringYour SKU or PLU. Promotions target it through products
categories[]{ id, name? }Promotions target these through categories
priceinteger centsUnit price excluding modifiers
quantityinteger1 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:

Errors

StatusCodeWhen
400INVALID_REQUESTBody failed validation; issues[] says where
401UNAUTHORIZEDMissing or invalid credential, or ?api_key= in production
409OFFERS_RESERVEDWith 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
409EVALUATION_TERMINALWith lock: this evaluation_id is already committed, cancelled, rolled_back or expired. Carries state. Start a new evaluation_id
503OFFERS_UNAVAILABLEThe 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

NameTypeDescription
customerstringLoyalty customer identifier
store_idstringStore
channelstringChannel

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

StatusCodeWhen
400INVALID_REQUESTInvalid query parameter
401UNAUTHORIZEDMissing 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

NameDescription
idredemption_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

StatusCodeWhen
401UNAUTHORIZEDMissing or invalid credential
404NOT_FOUNDNo 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

StatusCodeWhen
401UNAUTHORIZEDMissing or invalid credential
404NOT_FOUNDNo 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

StatusCodeWhen
401UNAUTHORIZEDMissing or invalid credential
404NOT_FOUNDNo 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

FieldTypeRequiredDescription
line_idsstring[]Yes1 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

StatusCodeWhen
400INVALID_REQUESTline_ids missing or empty
400UNKNOWN_LINESSome ids are not in this redemption. Carries unknown_line_ids
401UNAUTHORIZEDMissing or invalid credential
404NOT_FOUNDNo such redemption for this vendor
409INVALID_STATEThe 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

NameDescription
keylock.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

StatusCodeWhen
401UNAUTHORIZEDMissing or invalid credential
404NOT_FOUNDUnknown, 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.

FieldTypeDescription
typestringorder.submitted or order.voided
vendor_idstringVendor
receipt_numberstringThe evaluation_id
discount_idsstring[]order.submitted only: the discount ids on the order, compared with what was evaluated
order_referencestringorder.submitted only: the order id, stored on the record
event_idstringDe-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

FieldTypeDescription
identifierstringOptional on create: your id for the promotion. Minted when omitted. new, simulate, policy, loyalty-rewards, history, usage, . and .. are reserved (any case)
namestringGuest-facing name, 1 to 256 characters. Required
notesstringOperator note, up to 2000 characters
statusstringOn create only: draft, active or paused. Use the lifecycle routes afterwards
expected_versionintegerRequired on PUT. Refused on create
pos_referencestringPOS 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_typeFieldsEffect
PERCENTdiscount_amount (0 to 100), scope, amount_limit, max_quantity, min_quantity, modifier_policyPercent off the targeted items (scope: "item") or the order (scope: "order"). amount_limit caps the total discount in cents
AMOUNTdiscount_amount (cents), scope, max_quantity, min_quantity, modifier_policyCents off each targeted unit (item) or off the order (order)
FIXED_PRICEdiscount_amount (cents), max_quantity, include_modifiersTargeted 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_ITEMfree_item_sku, max_quantityZeroes that SKU when it is in the cart. When it is not, the offer is applicable with an add_item_hint
BUY_X_GET_YbogoBuy the trigger set, get the reward set free or at percent off. See below
TIEREDspend_tiersOrder-level discount by spend threshold. See below
BUNDLEbundleCombo price for one complete set of components. See below

Item-scope knobs on PERCENT and AMOUNT:

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

FieldTypeDescription
productsstring[]SKUs (cart line id) that can receive the discount
categoriesstring[]Category ids that can receive the discount
exclude_productsstring[]SKUs that never receive it
exclude_categoriesstring[]Categories that never receive it

Exclusions win over inclusions. Up to 50 entries each.

Conditions

FieldTypeDescription
min_spendinteger centsMinimum subtotal, else MIN_SPEND_NOT_MET with shortfall. The vendor policy's min_spend_basis decides which subtotal
tiersstring[]Loyalty tier ids allowed, else TIER_NOT_ELIGIBLE
segmentsstring[]Customer segments allowed, else CONDITION_NOT_MET
first_order_onlybooleanOnly for a customer with no previous orders. Fails closed when the order count is unknown
customer_tagsstring[]The customer carries at least one of these tags (1 to 50, up to 64 characters each)
requires_customerbooleanRefuse unidentified guests with CUSTOMER_REQUIRED. Default false: promotions are open to guests

Schedule and placement

FieldTypeDescription
active{ start?, end? }ISO 8601 instants with offset. Outside it: OUTSIDE_ACTIVE_WINDOW
daypartsarray[{ days?, start?, end? }]. days 0 (Sunday) to 6; start inclusive and end exclusive, HH:MM 24-hour. Outside every daypart: OUTSIDE_DAYPART
storesstring[]Store ids allowed, else STORE_NOT_ELIGIBLE
channelsstring[]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

FieldTypeDescription
stacking.exclusivebooleanNothing else applies once this does
stacking.priorityinteger-1000 to 1000, default 0. Higher goes first
stacking.groupstringOne applied promotion per group
requires_codestringThe code that unlocks it. Without the code the offer is not shown at all
auto_applybooleanApplies without being selected in manual mode
single_usebooleanOne use per customer. Implies requires_customer
usage_limits.max_totalintegerCommitted uses across all customers, else USAGE_LIMIT_REACHED
usage_limits.max_per_customerintegerCommitted uses per customer. Implies requires_customer
usage_limits.max_per_dayintegerCommitted uses per UTC day
usage_limits.budget_centsintegerTotal discount this promotion may ever give, else BUDGET_EXHAUSTED
fundingstringWho pays: restaurant (default), channel, shared, loyalty. Attribution only
funding_split.restaurant_bpsintegerRequired 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

NameTypeDescription
statusstringdraft, active, paused or archived
limitinteger1 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

StatusCodeWhen
400INVALID_REQUESTInvalid status or limit
401UNAUTHORIZEDMissing 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

StatusCodeWhen
400INVALID_REQUESTValidation failed (see below), expected_version sent, or a reserved identifier
401UNAUTHORIZEDMissing or invalid credential
403FORBIDDENOIDC caller with the viewer role
409PROMOTION_EXISTSThe 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

NameDescription
idThe 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

StatusCodeWhen
401UNAUTHORIZEDMissing or invalid credential
404NOT_FOUNDNo 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

StatusCodeWhen
400INVALID_REQUESTValidation failed
401UNAUTHORIZEDMissing or invalid credential
403FORBIDDENOIDC caller with the viewer role
404NOT_FOUNDNo such promotion for this vendor
409VERSION_REQUIREDexpected_version missing. Carries version. A missing version is never treated as "overwrite"
409VERSION_CONFLICTexpected_version is stale. Carries version and promotion
409PROMOTION_ARCHIVEDArchived 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

StatusCodeWhen
400INVALID_REQUESTexpected_version is not an integer
401UNAUTHORIZEDMissing or invalid credential
403FORBIDDENOIDC caller with the viewer role
404NOT_FOUNDNo such promotion for this vendor
409VERSION_CONFLICTexpected_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

StatusCodeWhen
401UNAUTHORIZEDMissing or invalid credential
404NOT_FOUNDNo 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

FieldTypeRequiredDescription
cartobjectYesSame as POST /v1/evaluate
customerobjectWhat-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_idSame as POST /v1/evaluate
nowISO 8601Evaluate as of this instant (dayparts, active windows). Default now
include_draftsbooleanAdd the vendor's draft promotions to the candidates
promotion_idsstring[]Evaluate exactly these promotions, whatever their status, and no loyalty rewards
evaluation_idstringEchoed 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

StatusCodeWhen
400INVALID_REQUESTValidation failed, or a promotion_ids entry is unknown or another vendor's (listed in unknown_promotion_ids)
401UNAUTHORIZEDMissing or invalid credential
503OFFERS_UNAVAILABLEThe 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

NameTypeDescription
daysinteger1 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

StatusCodeWhen
400INVALID_REQUESTdays out of range
401UNAUTHORIZEDMissing or invalid credential
404NOT_FOUNDNo such promotion for this vendor
503OFFERS_UNAVAILABLEThe 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

NameTypeDescription
limitinteger1 to 200, default 50
beforestringThe 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

StatusCodeWhen
400INVALID_REQUESTInvalid limit or before
401UNAUTHORIZEDMissing or invalid credential
404NOT_FOUNDNo such promotion for this vendor
503OFFERS_UNAVAILABLEThe 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.

SettingValuesDefaultEffect
max_applied_offers1 to 505Most offers applied to one order. Beyond it: MAX_OFFERS_REACHED
order_percent_modecascade, additivecascadecascade: each order-level percent applies to what the previous ones left. additive: each applies to the same post-item-discount base
max_order_discount_percent0 to 100noneCeiling 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? }noneItems no promotion may touch (gift cards, alcohol, deposits): never discounted, never counted in an order-level base
min_spend_basissubtotal, eligiblesubtotalWhat min_spend and spend tiers compare against. eligible is the subtotal minus excluded items and POS discounts
local_discount_policyrespect, ignorerespectrespect: 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

StatusCodeWhen
401UNAUTHORIZEDMissing 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

StatusCodeWhen
400INVALID_REQUESTValidation failed
401UNAUTHORIZEDMissing or invalid credential
403FORBIDDENOIDC caller with the viewer role
409VERSION_REQUIREDexpected_version missing. Carries the current version
409VERSION_CONFLICTexpected_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

StatusCodeWhen
401UNAUTHORIZEDMissing 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:

Inactive rewards, Loyalty Pay (a tender, not a discount) and information-only rows appear in neither list.

unpriced entries:

FieldTypeDescription
vendor_perk_redemption_idintegerThe reward's id in the loyalty program
namestringReward name
catalog_identifierstringThe loyalty catalog identifier (the POS code), when the reward has one
pos_referencestringdiscount_<identifier>, with the identifier exactly as the loyalty program sends it, and not doubled when it already starts with discount_
cost_pointsintegerPoint cost, when the reward has one
pos_idsstring[]POS ids, ascending, when the reward's data is keyed by point of sale
reasonstringPOS_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

StatusCodeWhen
401UNAUTHORIZEDMissing or invalid credential
503OFFERS_UNAVAILABLEConnected, 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

NameTypeRequiredDescription
statestringpending, sent, dead or skipped
limitinteger1 to 200. Default 50

Any other parameter is a 400.

States:

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

StatusCodeWhen
400INVALID_REQUESTA bad query parameter
401UNAUTHORIZEDMissing 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

StatusCodeWhen
401UNAUTHORIZEDMissing or invalid credential
403FORBIDDENRead-only role
404NOT_FOUNDNo such row for this vendor
409NOT_RETRYABLEThe 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

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

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

StatusCodeWhen
400KEY_MISMATCHThe key sent does not match the hash
401UNAUTHORIZEDMissing or invalid credential
403FORBIDDENNot the admin role
404NOT_FOUNDNo such key for this merchant
409AMBIGUOUSMore than one key starts with this prefix
409NOT_REVOKEDThe key is not revoked
409STILL_REJECTEDThe loyalty program still does not accept the key. reason says why
409FOREIGN_MASTERThe key belongs to another merchant
503UPSTREAM_UNAVAILABLEThe 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.

  1. Pay pressed: POST /partners/pos/check with the full check. Send it again if the cart changes; each call replaces the hold.
  2. Apply subtotal_discount as one subtotal discount, or each discounts[] entry on its line. Take payment.
  3. Check closed: POST /partners/pos/close, always, even when check failed or timed out.
  4. 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

Timeouts and retries

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

FieldTypeRequiredDescription
check_idstringYesYour 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
linesarrayYesUp to 200 lines, see below
customer_codestringThe 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
customerobjectThe 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
codesstring[]Coupon or promo codes. At most 50
selected_offer_idsstring[]The offer_id of each reward or promotion the customer wants to use. At most 50
channelstringDefault pos. Free-form; recommended pos, dine_in, takeout, drive_thru, delivery, kiosk. Promotions can be limited to channels
discountsarrayDiscounts the POS already took off the whole check: { id, name?, amount }, cents. At most 50. They lock no line
subtotalinteger centsThe 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.
cashierobject{ id, name? }, each 1 to 50 characters. Logged
metadataobjectYour 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_idstringLogged only
pos_transaction_idstringLogged 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"
}

Errors

StatusCodeWhenPOS action
400INVALID_REQUESTValidation failed: decimals, duplicate line_id, unknown fields, a colon in an id, two customer identifiers (including customer_code with customer), any limitFix the integration; do not retry
401UNAUTHORIZEDMissing or unknown POS key, or one the loyalty program no longer acceptsProceed without discount
413PAYLOAD_TOO_LARGEThe body is over 256 KBFix the integration; proceed without discount
429RATE_LIMITEDToo many requests for this key. Retry-After gives the seconds to waitWait that long and retry; if it does not clear, proceed without discount
409CHECK_CLOSEDThe check already closed or was refunded. Carries state and evaluation_idNew sale, new check_id
409CHECK_REOPEN_LIMITAll 10 evaluation ids usedNew check_id
409OFFERS_RESERVEDLost the race for a single-use reward three timesRe-send once, else proceed without discount
503OFFERS_UNAVAILABLEPromotions, policy or database could not be read, or a member lookup failedProceed without discount; always close
503CUSTOMER_LOOKUP_UNAVAILABLEA customer.qr_token could not be resolved (not available yet)Proceed without discount; always close
500INTERNALA bug on Spoonity's sideAs 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

FieldTypeRequiredDescription
check_idstringYesAs on check
pos_transaction_idstringYesYour id for this closed transaction. The idempotency key
receipt.discountsarrayYesThe 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.linesarrayYesThe final lines, same shape and limits as on check. Posted to the loyalty program for points when the forward is on
receipt.totalinteger centsYesThe receipt total before tax, after every discount. Posted to the loyalty program
receipt.pos_discountsarrayYour own check-level discounts as applied, { id, name?, amount }. At most 50. Recorded
receipt.taxesarrayThe 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.tipinteger centsRecorded; not posted (the loyalty program has no field for it)
receipt.paymentsarray{ method, amount }, method 1 to 64 characters, at most 50. Recorded; not posted (no field for it)
receipt.metadata, metadataobjectYour own fields, as on check
cashierobject{ 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_codestringAs on check: the scanned card number, the simple form of customer: { "customer_id": ... }. Send customer_code or customer, not both
customerobjectThe 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_idstringWhen it is 1 to 9 digits, the till number in the loyalty program; otherwise till 0
closed_atISO 8601 with offsetWhen 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:

reasonMeaning
NO_PENDING_EVALUATIONSpoonity 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_EXPIREDThe 15-minute hold had lapsed. The reward was not consumed
EVALUATION_CANCELLEDThe check was voided while open, or the last check answered 409 OFFERS_RESERVED
EVALUATION_ROLLED_BACKThe transaction was already voided

Apart from NO_PENDING_EVALUATION, the body also carries redemption_id, evaluation_id and state.

Errors

StatusCodeWhen
400INVALID_REQUESTValidation failed
401UNAUTHORIZEDMissing or unknown POS key, or one the loyalty program no longer accepts
413PAYLOAD_TOO_LARGEThe body is over 256 KB
429RATE_LIMITEDToo many requests for this key. See Retry-After
503OFFERS_UNAVAILABLEThe 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

FieldTypeRequiredDescription
check_idstringYesAs on check
pos_transaction_idstringYesIdempotency key for the void
terminal_idstringLogged 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

StatusCodeWhen
400INVALID_REQUESTValidation failed
401UNAUTHORIZEDMissing or unknown POS key, or one the loyalty program no longer accepts
413PAYLOAD_TOO_LARGEThe body is over 256 KB
429RATE_LIMITEDToo many requests for this key. See Retry-After
503OFFERS_UNAVAILABLEThe 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

NameTypeRequiredDescription
channelstringDefault pos
customerstringA 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

StatusCodeWhen
400INVALID_REQUESTAn unknown parameter
401UNAUTHORIZEDMissing or unknown POS key, or one the loyalty program no longer accepts
413PAYLOAD_TOO_LARGEThe body is over 256 KB
429RATE_LIMITEDToo many requests for this key. See Retry-After
503OFFERS_UNAVAILABLEPromotions or policy could not be read
503CUSTOMER_LOOKUP_UNAVAILABLEThe 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

FieldTypeRequiredDescription
card_numberstringYesThe scanned code, prefix included. Offers removes the merchant's code prefix
amountintegerYesSigned cents: positive loads, negative redeems. Sent on as decimal dollars (-1250 becomes -12.5)
tillintegerRequired by the loyalty platform
receipt_numberstringRequired by the loyalty platform. Unique per attempt
cashierobject{ 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

StatusCodeWhen
400INVALID_REQUESTamount is not an integer, or card_number is missing or empty
401UNAUTHORIZEDMissing or unknown POS key, or a key that is not a Spoonity API key
503QUICKPAY_UNAVAILABLEThe 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

FieldTypeRequiredDescription
reward_idintegerOne of the twoThe loyalty reward id (vendor_perk_redemption_id). Maps to offer off_r<reward_id>
offer_idstringOne of the twoThe 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

StatusCodeWhen
400INVALID_REQUESTValidation failed, including both or neither of reward_id and offer_id
401UNAUTHORIZEDHeader missing, session invalid, vendor not set up, or no loyalty account
409OFFER_NOT_AVAILABLEThe customer cannot have the reward now. error.reason is { code, message }, a code from Reason codes or OFFER_NOT_FOUND
409TOO_MANY_SELECTIONS10 open picks today already
413PAYLOAD_TOO_LARGEThe body is over 256 KB
429RATE_LIMITEDToo many requests. See Retry-After
503LOYALTY_UNAVAILABLEThe 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

StatusCodeWhen
401UNAUTHORIZEDHeader missing, session invalid, vendor not set up, or no loyalty account
429RATE_LIMITEDToo many requests. See Retry-After
503LOYALTY_UNAVAILABLEThe 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

StatusCodeWhen
401UNAUTHORIZEDHeader missing, session invalid, vendor not set up, or no loyalty account
404NOT_FOUNDNo such pick for this customer
409SELECTION_USEDThe check that applied it has closed
429RATE_LIMITEDToo many requests. See Retry-After
503LOYALTY_UNAVAILABLEThe 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.

CodeStatusMeaningExtra fields
MIN_SPEND_NOT_METinapplicableSubtotal below min_spendshortfall (cents); basis: "eligible" when the policy uses the eligible subtotal
NO_ELIGIBLE_ITEMSapplicableA free item offer whose SKU is not in the cart. The offer also carries add_item_hint: { sku }
OUTSIDE_ACTIVE_WINDOWinapplicableBefore active.start or after active.end
OUTSIDE_DAYPARTinapplicableOutside every daypart
TIER_NOT_ELIGIBLEinapplicableThe customer's loyalty tier is not in tiers
INSUFFICIENT_BALANCEinapplicableNot enough points for a point-cost reward (a guest has 0)required, balance
CODE_REQUIREDinapplicableSimulate explain only: a code-gated offer whose code was not entered. Evaluate leaves such offers out
CONDITION_NOT_METinapplicableAnother condition failed (segment, tag, first order, order count, store, channel condition)attribute
STORE_NOT_ELIGIBLEinapplicablestore_id not in stores
CHANNEL_NOT_ELIGIBLEinapplicablechannel not in channels
EXCLUSIVE_CONFLICTskippedAn exclusive offer applied, or this exclusive offer could not apply alongside those already applied
LOWER_VALUE_THAN_APPLIEDReserved. Not emitted today
UNIT_CONFLICTskippedThe units it needs already carry another offer's discount
MAX_OFFERS_REACHEDskippedThe policy's max_applied_offers was reached
ZERO_DISCOUNTskippedIt would not reduce the total (for example, the order is already fully discounted)
ALREADY_USEDinapplicableA single-use offer this customer already redeemed
RESERVEDinapplicableA single-use offer held by another order in progress
CUSTOMER_REQUIREDinapplicableThe offer needs an identified customerbecause: "single_use" when implied by single use or a per-customer cap
USAGE_LIMIT_REACHEDinapplicableA usage limit was reachedscope (total, per_customer, per_day), limit, used
BUDGET_EXHAUSTEDinapplicablebudget_cents is spentbudget_cents, spent_cents
GROUP_CONFLICTskippedAnother offer in the same stacking.group appliedgroup, applied_offer_id
LOCALLY_DISCOUNTEDskippedThe units it needs carry a POS line discount and the policy is respect. Check-level POS discounts never cause it
ORDER_CAP_REACHEDskippedTrimmed to nothing by max_order_discount_percentcap
MIN_QUANTITY_NOT_METinapplicableFewer eligible units than min_quantityrequired, eligible
TIER_NOT_REACHEDinapplicableNo spend tier reachednext_min_spend, shortfall
BUNDLE_INCOMPLETEapplicableThe cart does not hold a complete combo setmissing: [{ 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.

StatusCodeMeaning
400INVALID_REQUESTValidation failed. issues[] lists { path, message }
400UNKNOWN_LINESPartial return named lines that are not in the redemption
401UNAUTHORIZEDMissing or invalid credential
403FORBIDDENRead-only role attempted a write
404NOT_FOUNDUnknown route, or a resource that does not exist for this vendor
409OFFERS_RESERVEDA single-use offer is held by another order
409EVALUATION_TERMINALThe evaluation_id is already finished
409VERSION_REQUIREDAn update without expected_version
409VERSION_CONFLICTAn update with a stale expected_version
409PROMOTION_ARCHIVEDAn edit to an archived promotion
409PROMOTION_EXISTSCreate with an identifier that is taken
409INVALID_STATEA redemption in the wrong state for the action
409CHECK_CLOSEDPOS: the check already closed
409CHECK_REOPEN_LIMITPOS: the check has no evaluation ids left
409OFFER_NOT_AVAILABLEApp: the customer cannot have the reward now. error.reason says why
409TOO_MANY_SELECTIONSApp: 10 open picks today already
409SELECTION_USEDApp: the pick was used by a check that closed
409NOT_RETRYABLELoyalty outbox: only a dead row can be retried
413PAYLOAD_TOO_LARGEThe request body is over 256 KB. Any route
429RATE_LIMITEDToo many requests for this key. Retry-After gives the seconds to wait. POS and app routes
500INTERNALUnexpected server error
503OFFERS_UNAVAILABLECatalog, policy, loyalty source or database unavailable. Retryable
503CUSTOMER_LOOKUP_UNAVAILABLEPOS: a customer QR token could not be resolved. Retryable
503LOYALTY_UNAVAILABLEApp: the merchant's loyalty host could not be reached. Retryable
503QUICKPAY_UNAVAILABLEPOS 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

See also