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": 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": 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. 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).
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
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": 401,
"message": "There was an error authenticating you."
}