Skip to main content
POST
Use this endpoint to surface “applicable” offers to a customer before checkout (e.g. an offers carousel that only shows rewards the customer can use against the current basket). For the full unfiltered list of what the user owns, use Get Account instead.
Read-only dry-run of Create & Update Basket — same eligibility and discount-calculation logic, no state mutation, no points debit. It accepts the same request body shape, including the flat, top-level location_uid string used for location-restricted rewards.

​
Overview

POST /baskets/qualifying is a dry-run companion to Create & Update Basket:
  • POST /baskets runs the full reward redemption pipeline (state machine, validation, side effects).
  • POST /baskets/qualifying runs the same eligibility and discount calculation logic, but does not mutate state, does not redeem any reward, and does not debit points. It returns the rewards and points products that would apply if the basket were submitted as-is.
A reward returned by this endpoint is one that Create & Update Basket would accept for the same basket shape — the two endpoints share the same applicability check.

​
HTTP Request

​
Parameters

Every field is optional on this endpoint. Unlike Create & Update Basket — where fields such as location_uid, items, and subtotal are required — /baskets/qualifying accepts them all optionally; omitting a field simply reduces the precision of the qualifying set (see the per-field notes below). Any field accepted by Create & Update Basket is also accepted here and forwarded into the discount calculation engine unchanged.
​
string
Either instore or online. Defaults to online when omitted, which only surfaces rewards whose redemption_venue is online or all.
​
string
Order timestamp used by time-restricted reward eligibility, in ISO 8601 (UTC). Defaults to the current server time when omitted.
​
string
Thanx Location UID, used to apply reward location restrictions — the same flat, top-level location_uid accepted by Create & Update Basket.A mapping of Thanx location identifiers can be provided by the Thanx developer support team or fetched from the following endpoints depending on your integration type:
Locations belonging to a different merchant than the one the access token resolves to are silently dropped.
​
array(hash)
Basket items. Same shape as Create & Update Basket — modifiers are nested under each item.
​
decimal
Basket subtotal in USD (pre-discount). Include it so minimum-gated rewards can be evaluated — without it, minimum-gated rewards are treated as not-yet-qualifying and filtered out.

​
Response

200 OK with a JSON body containing two arrays: rewards and points_products.
​
array(RewardEntity)
Rewards the user owns that (1) pass eligibility (state, ownership, location, time restrictions, handoff, expiration), AND (2) would produce a positive discount against the supplied basket.Ordering: effective expiration ascending (soonest-to-expire first); rewards without an expiration are placed last; reward id is the tiebreaker.
​
array(PointsProductEntity)
Points-exchange products the user can afford AND that would produce a positive discount against the supplied basket.

​
Empty basket behavior

A basket with no items and no subtotal always returns empty arrays:
This is intentional — nothing in the user’s portfolio can produce a positive discount against a nonexistent basket. Treat empty arrays as “no applicable offers for the current basket” rather than “the user has no offers at all”; for the full unfiltered list, use Get Account.

​
Notes for implementation

Call frequency. Safe to call on every basket change (item added or removed, quantity changed). The endpoint is read-only and does not mutate user or merchant state.
Do not cache responses across baskets. The qualifying set changes with basket contents — caching defeats the purpose of the endpoint.
  • Item prices: include price on each item so item-redeem rewards (free item, BOGO) are evaluated. Without prices, item-type rewards resolve to a $0 discount and are filtered out.
  • Location and timestamp: include location_uid and order_timestamp when known so location-restricted and time-restricted rewards filter correctly. Omitting these is safe — they default to “no restriction match” / “current server time” — but means location-restricted offers may surface for baskets that ultimately won’t be eligible at checkout.
  • Handoff restrictions: rewards limited to a specific handoff mode (e.g. a delivery-only offer) are returned only when the request body’s handoff matches the reward’s restriction; omit handoff and those rewards are filtered out. As with Create & Update Basket, handoff is read from the request body and applied to reward eligibility.
  • Redemption still requires POST /baskets. A reward returned here is one that Create & Update Basket would accept for the same basket. Calling /baskets/qualifying does not redeem anything; partners must still call /baskets at checkout to actually apply the reward.

​
Error responses

  • Create & Update Basket — the redemption endpoint; the same applicability check used here.
  • Get Account — full unfiltered list of the user’s rewards and affordable points products (no basket filtering).
  • Loyalty API Headers — required Authorization, Merchant-Key, and Accept headers.