Cart and checkout

A cart is the authoritative pricing and eligibility snapshot for checkout. Re-read the returned cart after every mutation because lines, discounts, tax, shipping options, availability, and totals can change together.

Create a cart

Use the same market context as the product query:

Keep the cart ID in durable application state. Never calculate a payable total from cached product prices; use cart.total.

Choose hosted or custom checkout

For hosted checkout, redirect the shopper to cart.checkoutUrl. This is the shortest path and keeps the payment user interface aligned with Thor’s checkout configuration.

For a custom checkout:

  1. Add, update, or remove line items.
  2. Set customer email and billing or shipping addresses with cartUpdate.
  3. Read availableShippingMethods, then set selected methods with cartShippingLinesSet.
  4. Query paymentGateways for the cart. Eligibility can depend on the cart predicate, including customer group and cart totals.
  5. Initialize the selected gateway with cartPaymentSessionInitialize. Follow the returned gateway-specific session data and confirmation flow.
  6. Call cartComplete only after the cart satisfies its address, shipping, stock, and payment requirements.

Concurrency and recovery

Serialize mutations for a single cart in the client. If two tabs or rapid button presses update the same cart, use the latest returned cart as the source of truth and re-query after an ambiguous network failure.

Disable the final submit control after the first attempt, but do not assume a timeout means failure. Re-query the cart or resulting checkout session before repeating payment or completion steps. Payment providers can complete asynchronously through webhooks.

Always render typed payload errors near the relevant step and preserve the shopper’s input. A cart can become invalid between review and completion because price validity, stock, discounts, or gateway eligibility changed.