Carts and line items

A cart is the editable purchase record before order placement. It holds line items, customer and address information, shipping, discount applications, and calculated amounts. Use its returned values as the current state of the buying experience.

One shopping session, one current cart

Persist the returned cart ID with the shopper’s session. Use it for later mutations and replace displayed state with the latest returned cart. Avoid creating a new cart for every Add to cart click. Serialize updates that depend on the same cart so a slower response cannot overwrite newer state.

A variant ID identifies what is being bought. A cart line-item ID identifies the existing line to update or remove. Do not substitute one for the other.

Managed and custom lines

Managed lines refer to catalog variants and use Thor’s price and availability context. Custom lines describe items outside the catalog and have a different input contract. Use managed lines for ordinary product purchases. Never treat a browser-supplied custom amount as a trusted way to override a catalog price.

A cart carries commerce context

Choose the store and currency before adding lines. Keep price channel, country, and customer context aligned with product discovery. Address, customer, and discount changes can affect several returned amounts at once. See Storefront request context.

After completion

An ordered cart is no longer the shopper’s editable basket. Retain its relationship to the completed order and start a new shopping session deliberately. For a supported repeat-purchase flow, inspect cartReplicate and its unavailable-item behavior.

Follow Build a cart and checkout for the implementation sequence.