> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tip>
  Integrating for the first time? Start with the [Basket Lifecycle & Troubleshooting guide](/overview/guides/basket-lifecycle) for behavioral context and common-mistake coverage.
</Tip>

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

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

<Note>
  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](/consumer/best-practices/loyalty#rewards-vs-points-products).
</Note>

```mermaid theme={null}
  flowchart LR
    Checkout --> Placed
    Placed --> Voided
    Placed --> Billed
    Billed --> Refunded
    Billed --> Completed
    Completed --> Refunded

    classDef default fill:transparent,stroke:#13c1bf,stroke-width:1px;
```

## HTTP Request

### Parameters

<ParamField body="id" type="string">
  Basket unique ID. Partner-generated: your system creates this value and reuses it across every state transition for the same basket.

  <Note>
    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.
  </Note>
</ParamField>

<ParamField body="state" type="enum" required>
  Basket state (`checkout`, `placed`, `billed`, `completed`, `voided`,
  `refunded`)
</ParamField>

<ParamField body="order_timestamp" type="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).
</ParamField>

<ParamField body="location_uid" type="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](/consumer/locations/get-locations) endpoint.
  * Partner API [Get Locations](/partner/metadata/get-locations) endpoint.
</ParamField>

<ParamField body="rewards" type="array(string)">
  Reward IDs to apply to the basket.

  **These IDs must be obtained from the rewards field at the [Get Account API](/loyalty/get-account) response.**

  If you are integrating with reward codes,
  provide the reward code here instead.

  <Note>
    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.
  </Note>
</ParamField>

<ParamField body="points_products" type="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](/loyalty/get-account) response.**

  <Note>
    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.
  </Note>
</ParamField>

<ParamField body="promo_code" type="string">
  <Warning>
    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.
  </Warning>

  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.

  <Note>
    A promo code cannot be combined with a reward or points product. Supplying
    both returns a 400 — apply one or the other, not both.
  </Note>

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

  <Note>
    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).
  </Note>
</ParamField>

<ParamField body="payments" type="array(hash)">
  Array of payment methods

  <Expandable title="payment">
    <ParamField body="last4" type="string">
      Last 4 digits of the payment method
    </ParamField>

    <ParamField body="issuer" type="string" required>
      Issuer of the payment method
    </ParamField>

    <ParamField body="amount" type="decimal" required>
      <Note>
        Required to generate the purchase and points to the user.
      </Note>

      Amount used with the payment method
    </ParamField>

    <ParamField body="authorized_at" type="string" required>
      The timestamp of when the authorization was submitted to the issuer, in **ISO8601 format. The timestamp must be expressed in UTC.**
    </ParamField>
  </Expandable>

  <Note>
    Currently only a single object is supported. If multiple entries are provided, only the first will be validated and the rest will be ignored.
  </Note>
</ParamField>

<ParamField body="items" type="array(hash)" required>
  Array of items

  <Expandable title="item">
    <ParamField body="id" type="string">
      Item ID in your system / POS
    </ParamField>

    <ParamField body="name" type="string">
      Item name
    </ParamField>

    <ParamField body="price" type="decimal">
      Item amount
    </ParamField>

    <ParamField body="categories" type="array(string)">
      categories that describe this item
    </ParamField>

    <ParamField body="modifiers" type="array(hash)">
      Array of modifiers for this item

      <Expandable title="modifier">
        <ParamField body="id" type="string">
          Modifier ID in your system / POS
        </ParamField>

        <ParamField body="name" type="string">
          Modifier name
        </ParamField>

        <ParamField body="price" type="decimal">
          Modifier price adjustment
        </ParamField>

        <ParamField body="item_base_price" type="decimal">
          Base price of the item before modifiers
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="subtotal" type="decimal" required>
  The subtotal of the basket in USD (before taxes & tips)
</ParamField>

<ParamField query="redemption_venue" type="string" optional>
  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.
</ParamField>

### Response

<ResponseField name="id" type="string">
  Response ID
</ResponseField>

<ResponseField name="state" type="enum">
  Basket state (`checkout`, `placed`, `billed`, `completed`, `voided`,
  `refunded`)
</ResponseField>

<ResponseField name="discount" type="string">
  Discount to apply
</ResponseField>

<RequestExample>
  ```bash Reward theme={null}
  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
    }'
  ```

  ```bash Promo code theme={null}
  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
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "fhwerwe-23663-ryryre",
    "state": "checkout",
    "discount": "10.25"
  }
  ```

  ```bash 400 Invalid reward theme={null}
  {
    "code": 400,
    "message": "The reward was not found in our system"
  }
  ```

  ```bash 400 Reward conflict theme={null}
  {
    "code": 400,
    "message": "A promo code cannot be combined with a reward or points product"
  }
  ```

  ```bash 400 Invalid promo theme={null}
  {
    "code": 400,
    "message": "This promo code is not valid"
  }
  ```

  ```bash 401 theme={null}
  {
    "code": 401,
    "message": "There was an error authenticating you."
  }
  ```
</ResponseExample>