Carts and line items
A cart is the mutable commerce record used before order placement. It retains store, currency, optional price channel, customer details, addresses, lines, discounts, shipping, payment session, calculated totals, and a lifecycle state.
Persist one cart ID
Create a cart once and store its opaque ID with the shopper’s session. Send that ID to every cart mutation and replace local cart data with the cart returned by the mutation. Parallel changes can otherwise render the UI from stale totals or quantities.
Managed and custom lines
Managed line items reference a product variant. Thor resolves their product snapshot, unit price, availability, tax, and discounts from the cart context. Custom line items provide their own product description and price data and are not backed by catalog inventory.
Use managed lines for normal catalog purchases. Use custom lines only when the application deliberately owns product identity and price; custom inputs are not a way to override a managed variant’s price.
Context and addresses
cartCreate requires storeId and currency, and can accept country, price channel, customer information, lines, and addresses. Address changes can alter tax and shipping eligibility. A price-channel change can alter line prices. Always inspect the typed errors and render the returned cart after a change.
Lifecycle consequences
Before completion the cart remains editable. Completion creates or returns the associated order and moves the cart to ORDERED. An ordered cart is not an editable shopping session. Use cartReplicate when a supported replication flow is needed, and handle its stock and variant validation errors.