Create & Update Basket

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

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.

A basket can be in one of the following states:

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.

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.

A Universal Promo Code to apply to the basket, as a 1–64 character string.A promo code follows the same lifecycle as a reward:

checkout — the code is validated and the resulting discount is 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

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.

Amount used with the payment method

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

string

Item ID in your system / POS

string

Item name

decimal

Item amount

array(string)

categories that describe this item

array(hash)

Array of modifiers for this item

Show modifier

string

Modifier ID in your system / POS

string

Modifier name

decimal

Modifier price adjustment

decimal

Base price of the item before modifiers

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

Get Account

⌘I

Loyalty API

Reference

Create & Update Basket

HTTP Request

Parameters

Response

​HTTP Request

​Parameters

​Response

HTTP Request

Parameters

Response