Cart and checkout

A cart is the authoritative pricing and eligibility snapshot for checkout. It resolves line prices, discounts, tax, shipping, payment eligibility, and totals from the current commerce and customer context.

Use the latest cart returned by every mutation. A change to an item, address, discount, or customer can affect several downstream values at once.

Create the cart

Pass the store, price channel, currency, and country used for product discovery. Optional initial line items let Thor resolve a complete first cart response in one mutation.

Persist the cart ID in durable application state. Never calculate a payable total from cached product data; use the returned cart.total.

Always select the typed errors field alongside the cart. A nullable cart with payload errors is not a successful creation.

Build a custom checkout

A custom checkout is an ordered state machine. Re-read the returned cart before moving to the next step:

  1. Add, update, or remove line items.
  2. Set the customer email and billing or shipping address with cartUpdate.
  3. Read availableShippingMethods, then select rates with cartShippingLinesSet.
  4. Query paymentGateways for the current cart.
  5. Initialize the selected gateway with cartPaymentSessionInitialize.
  6. Call cartComplete only after shipping, stock, and payment requirements are satisfied.

Mutation safety and recovery

Serialize mutations for one cart and disable duplicate final submission. After an ambiguous network failure, re-query the cart or resulting order before repeating payment initialization or completion.

Do not assume a timeout means failure. Payment providers can complete asynchronously, and an automatic retry can create conflicting sessions or duplicate intent.

Prices, inventory, discounts, and gateway eligibility can change between review and completion. Preserve shopper input, render typed errors beside the affected step, and let the latest server result drive recovery.