curl https://loyalty.thanxsandbox.com/api/baskets \
-X POST \
-H "Authorization: Bearer ${token}" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.thanx-v1+json" \
-H "Merchant-Key: ${merchant_key}" \
-d '{
"id": "gwer-werwr-2134-rty",
"state": "billed",
"order_timestamp": "2019-05-08T18:02:05Z",
"location_uid": "LG-567fhwer",
"rewards": [
"fheTRR"
],
"payments": [
{
"issuer": "visa",
"last4": "1234",
"amount": 10.45,
"authorized_at": "2019-05-07T18:02:05Z"
}
],
"items": [
{
"id": "ng-23492",
"name": "Cheese Pizza",
"price": 9.95,
"categories": [
"pizza",
"vegetarian"
],
"modifiers": [
{
"id": "mod-123",
"name": "Extra Cheese",
"price": 1.50,
"item_base_price": 8.45
}
]
}
],
"subtotal": 23.45
}'
curl https://loyalty.thanxsandbox.com/api/baskets \
-X POST \
-H "Authorization: Bearer ${token}" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.thanx-v1+json" \
-H "Merchant-Key: ${merchant_key}" \
-d '{
"id": "order-abc-123",
"state": "billed",
"order_timestamp": "2026-06-08T18:02:05Z",
"location_uid": "LG-567fhwer",
"promo_code": "SUMMER10",
"payments": [
{
"issuer": "visa",
"last4": "1234",
"amount": 20.00,
"authorized_at": "2026-06-07T18:02:05Z"
}
],
"items": [
{
"id": "ng-23492",
"name": "Cheese Pizza",
"price": 20.00,
"categories": [
"pizza"
]
}
],
"subtotal": 20.00
}'
{
"id": "fhwerwe-23663-ryryre",
"state": "checkout",
"discount": "10.25"
}
{
"code": 400,
"message": "The reward was not found in our system"
}
{
"code": 400,
"message": "A promo code cannot be combined with a reward or points product"
}
{
"code": 400,
"message": "This promo code is not valid"
}
{
"code": 400,
"message": "hold_until must be at least 2 days from now"
}
{
"code": 400,
"message": "This reward expires before hold_until. Choose an earlier hold_until or a different reward"
}
{
"code": 401,
"message": "There was an error authenticating you."
}
Reference
Create & Update Basket
This endpoint is used to notify Thanx of the states that a basket is in, apply rewards to the order, and accrue loyalty progress or points for the order.
POST
/
api
/
baskets
curl https://loyalty.thanxsandbox.com/api/baskets \
-X POST \
-H "Authorization: Bearer ${token}" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.thanx-v1+json" \
-H "Merchant-Key: ${merchant_key}" \
-d '{
"id": "gwer-werwr-2134-rty",
"state": "billed",
"order_timestamp": "2019-05-08T18:02:05Z",
"location_uid": "LG-567fhwer",
"rewards": [
"fheTRR"
],
"payments": [
{
"issuer": "visa",
"last4": "1234",
"amount": 10.45,
"authorized_at": "2019-05-07T18:02:05Z"
}
],
"items": [
{
"id": "ng-23492",
"name": "Cheese Pizza",
"price": 9.95,
"categories": [
"pizza",
"vegetarian"
],
"modifiers": [
{
"id": "mod-123",
"name": "Extra Cheese",
"price": 1.50,
"item_base_price": 8.45
}
]
}
],
"subtotal": 23.45
}'
curl https://loyalty.thanxsandbox.com/api/baskets \
-X POST \
-H "Authorization: Bearer ${token}" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.thanx-v1+json" \
-H "Merchant-Key: ${merchant_key}" \
-d '{
"id": "order-abc-123",
"state": "billed",
"order_timestamp": "2026-06-08T18:02:05Z",
"location_uid": "LG-567fhwer",
"promo_code": "SUMMER10",
"payments": [
{
"issuer": "visa",
"last4": "1234",
"amount": 20.00,
"authorized_at": "2026-06-07T18:02:05Z"
}
],
"items": [
{
"id": "ng-23492",
"name": "Cheese Pizza",
"price": 20.00,
"categories": [
"pizza"
]
}
],
"subtotal": 20.00
}'
{
"id": "fhwerwe-23663-ryryre",
"state": "checkout",
"discount": "10.25"
}
{
"code": 400,
"message": "The reward was not found in our system"
}
{
"code": 400,
"message": "A promo code cannot be combined with a reward or points product"
}
{
"code": 400,
"message": "This promo code is not valid"
}
{
"code": 400,
"message": "hold_until must be at least 2 days from now"
}
{
"code": 400,
"message": "This reward expires before hold_until. Choose an earlier hold_until or a different reward"
}
{
"code": 401,
"message": "There was an error authenticating you."
}
Integrating for the first time? Start with the Basket Lifecycle & Troubleshooting guide for behavioral context and common-mistake coverage.
Need to surface only the rewards that would apply to the current basket (e.g. an offers carousel before checkout)? Use Qualifying Rewards for a Basket — a read-only dry-run that shares this endpoint’s applicability check without redeeming anything.
| State | Description |
|---|---|
checkout | required Refers to any point before the order is placed. Any time the user updates their basket or rewards, Thanx expects to receive a request to check if discount information should be updated. |
placed | required Refers to when an order has been submitted to the system and a user can no longer modify their order through the website. If a reward is specified, the reward will be locked and released back to the user after about 2 days unless the order is billed or voided first; to hold it longer, send hold_until. If a points product is specified, the user’s points balance will be deducted in exchange for specified reward and the reward will be locked. |
billed | required Refers to when the order has been trasmitted to the POS and the user’s credit card has been charged. Any specified reward will be marked as used. Loyalty progress or points will be accrued upon receipt of this event. |
completed | recommended Refers to when the order has been made and transferred to the customer. |
voided | recommended Refers to an order that got canceled after entering the placed state and before entering the billed state. Any locked reward is restored to the user and available for future use. For rewards obtained through a points exchange (points products), the reward instance is finalized as refunded and the points are returned to the user’s points balance — the user can re-exchange those points for a new reward. |
refunded | recommended Refers to an order being refunded / canceled any time after it enters the billed state. Any locked reward is restored to the user and available for future use. For rewards obtained through a points exchange (points products), the reward instance is finalized as refunded and the points are returned to the user’s points balance — the user can re-exchange those points for a new reward. |
Only a single reward, points product, or promo code can be applied per order. Supplying a promo code together with a reward or points product returns a 400.
For more on the difference between locked rewards and points-product rewards
when an order is voided or refunded, see
Loyalty Best Practices — Rewards vs Points Products.
HTTP Request
Parameters
string
Basket unique ID. Partner-generated: your system creates this value and reuses it across every state transition for the same basket.
Required for all states other than
checkout. A checkout request may omit the ID; every subsequent state (placed, billed, completed, voided, refunded) must send the same ID the basket was created with.enum
required
Basket state (
checkout, placed, billed, completed, voided,
refunded)string
required
When the order is wanted in (ISO 8601 in UTC). If this timestamp is not
provided, Thanx assumes the order is wanted ASAP.Providing this timestamp allows Thanx to determine if a reward will be valid in the future (for
example, for a weekend only promotion where the user orders in advance).
string
required
Thanx Location UID Providing this information allows Thanx to apply reward
location restrictions.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:
- Consumer API Get Locations endpoint.
- Partner API Get Locations endpoint.
array(string)
Reward IDs to apply to the basket.These IDs must be obtained from the rewards field at the Get Account API response.If you are integrating with reward codes,
provide the reward code here instead.
Currently only a single reward or points product can be applied to a
basket. The request will 400 if multiple rewards or points products are
specified in the request.
array(string)
Points Product IDs to apply to the basket.These IDs must be obtained from the points_products field at the Get Account API response.
Currently only a single reward or points product can be applied to a
basket. The request will 400 if multiple rewards or points products are
specified in the request.
string
Universal Promo Code support is being rolled out and must be enabled for your
account by Thanx before it can be used. Contact your Thanx representative to
request access.
checkout— the code is validated and the resultingdiscountis returned as a preview; nothing is redeemed yet.placed/billed/completed— the discount is applied and the redemption is recorded (once per basket).voided/refunded— any recorded redemption is released.
A promo code cannot be combined with a reward or points product. Supplying
both returns a 400 — apply one or the other, not both.
A basket
id is required when applying a promo code, and must be reused
across every state update for the basket. The id keys the redemption and
makes retries idempotent, so resending the same basket will not redeem twice.A member is not required to apply a promo code. If the basket is associated
with a member, the order still accrues loyalty as usual; if it is not, the
discount is applied and the redemption is recorded, but the order does not
accrue loyalty (there is no member to credit).
string
When to hold the applied reward until for this order, as an ISO 8601 timestamp with an explicit offset (
Z or +hh:mm), for example 2026-12-24T18:00:00Z. Use it for orders placed well before they are billed, such as catering or scheduled orders. See Holding a reward for scheduled orders.Default: when omitted, a reward on a placed basket is released back to the user’s wallet about 2 days after the basket was placed (the release job runs every 2 hours, so in practice 2 days to roughly 2 days 2 hours), whether or not the order has been billed or voided.Validated on the checkout and placed states, so you learn before placing an order that a hold can’t be honored. Later states ignore the field. The value must be:- in the future, and at least 2 days from now
- no more than 365 days from now
- before the reward’s expiration (including a points product’s projected reward expiration). A
hold_untilequal to the expiration is rejected.
Re-sending
placed with a later hold_until extends the hold; an earlier one never shortens it. Re-sending a hold_until the reward is already held through is accepted unchanged, even when it is under 2 days away. Omitting it on a re-send leaves the existing hold alone.array(hash)
Array of payment methods
Amount used with the payment method
Show payment
Show payment
string
Last 4 digits of the payment method
string
required
Issuer of the payment method
decimal
required
Required to generate the purchase and points to the user.
string
required
The timestamp of when the authorization was submitted to the issuer, in ISO8601 format. The timestamp must be expressed in UTC.
Currently only a single object is supported. If multiple entries are provided, only the first will be validated and the rest will be ignored.
array(hash)
required
Array of items
Show item
Show item
string
Item ID in your system / POS
string
Item name
decimal
Item amount
array(string)
categories that describe this item
decimal
required
The subtotal of the basket in USD (before taxes & tips)
string
Currently either
instore or online, defaults to online. This is used to
adjust which configured product IDs are returned in the applicable reward and
points product entities.Response
string
Response ID
enum
Basket state (
checkout, placed, billed, completed, voided,
refunded)string
Discount to apply
Holding a Reward for Scheduled Orders
By default, a reward on aplaced basket is released back to the user about 2 days after the basket was placed. For orders placed well ahead of the day they are billed, send hold_until so the reward stays reserved for the order until then.
checkout: send the event or fulfillment time ashold_until. If the reward would expire before that time, the request returns a400so you can ask the user to choose a different reward.placed: send the samehold_until. The reward is held until that time.billed: send the order as usual. Billing re-checks reward eligibility against theorder_timestampyou send, so use the same fulfillment time throughout.
hold_until, when the reward is released back to the user’s wallet. Billing, voiding, or otherwise releasing the reward before then also clears the hold.
Placed with hold_until
curl https://loyalty.thanxsandbox.com/api/baskets \
-X POST \
-H "Authorization: Bearer ${token}" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.thanx-v1+json" \
-H "Merchant-Key: ${merchant_key}" \
-d '{
"id": "order-abc-123",
"state": "placed",
"order_timestamp": "2026-12-24T18:00:00Z",
"hold_until": "2026-12-24T18:00:00Z",
"location_uid": "LG-567fhwer",
"rewards": [
"fheTRR"
],
"items": [
{
"id": "ng-23492",
"name": "Cheese Pizza",
"price": 20.00
}
],
"subtotal": 20.00
}'
If a reward expires before it can be billed,
billed returns 400 This reward will expire before the order is fulfilled.hold_until Errors
Each failure returns HTTP400 with {"code": 400, "message": ...}.
| Condition | Message |
|---|---|
| Not an ISO 8601 timestamp with an offset | hold_until is invalid |
| Matches the format but is not a real time (for example, month 13) | hold_until is not a valid time |
| In the past | hold_until must be in the future |
| Less than 2 days from now | hold_until must be at least 2 days from now |
| More than 365 days from now | hold_until must be no more than 365 days from now |
| At or after the reward’s expiration | This reward expires before hold_until. Choose an earlier hold_until or a different reward |
curl https://loyalty.thanxsandbox.com/api/baskets \
-X POST \
-H "Authorization: Bearer ${token}" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.thanx-v1+json" \
-H "Merchant-Key: ${merchant_key}" \
-d '{
"id": "gwer-werwr-2134-rty",
"state": "billed",
"order_timestamp": "2019-05-08T18:02:05Z",
"location_uid": "LG-567fhwer",
"rewards": [
"fheTRR"
],
"payments": [
{
"issuer": "visa",
"last4": "1234",
"amount": 10.45,
"authorized_at": "2019-05-07T18:02:05Z"
}
],
"items": [
{
"id": "ng-23492",
"name": "Cheese Pizza",
"price": 9.95,
"categories": [
"pizza",
"vegetarian"
],
"modifiers": [
{
"id": "mod-123",
"name": "Extra Cheese",
"price": 1.50,
"item_base_price": 8.45
}
]
}
],
"subtotal": 23.45
}'
curl https://loyalty.thanxsandbox.com/api/baskets \
-X POST \
-H "Authorization: Bearer ${token}" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.thanx-v1+json" \
-H "Merchant-Key: ${merchant_key}" \
-d '{
"id": "order-abc-123",
"state": "billed",
"order_timestamp": "2026-06-08T18:02:05Z",
"location_uid": "LG-567fhwer",
"promo_code": "SUMMER10",
"payments": [
{
"issuer": "visa",
"last4": "1234",
"amount": 20.00,
"authorized_at": "2026-06-07T18:02:05Z"
}
],
"items": [
{
"id": "ng-23492",
"name": "Cheese Pizza",
"price": 20.00,
"categories": [
"pizza"
]
}
],
"subtotal": 20.00
}'
{
"id": "fhwerwe-23663-ryryre",
"state": "checkout",
"discount": "10.25"
}
{
"code": 400,
"message": "The reward was not found in our system"
}
{
"code": 400,
"message": "A promo code cannot be combined with a reward or points product"
}
{
"code": 400,
"message": "This promo code is not valid"
}
{
"code": 400,
"message": "hold_until must be at least 2 days from now"
}
{
"code": 400,
"message": "This reward expires before hold_until. Choose an earlier hold_until or a different reward"
}
{
"code": 401,
"message": "There was an error authenticating you."
}