Build a cart and checkout

Create one cart, keep it current, and complete a purchase through hosted or custom checkout. The cart response supplies the current amounts and eligibility; the browser does not calculate the payable total independently.

Before you begin

Verify a sellable variant and matching request context. Use the Storefront quickstart to create the cart and persist its ID. Prepare the shipping, tax, and test payment configuration required by your project.

1. Edit the cart

Use cartLineItemsAdd with variant IDs to add items. Use cartLineItemsUpdate and cartLineItemsRemove with existing cart line-item IDs. Check business errors and render the latest cart after each response. Serialize dependent changes to avoid stale quantities and amounts.

Persist cart identity in the shopper’s session, not a global application variable. Check that the current cart is editable before continuing a previous session. An ordered cart belongs to the completed purchase.

2. Choose hosted or custom checkout

For hosted checkout, open the current cart’s checkoutUrl after verifying the basket. Your storefront still owns product discovery and cart presentation. You do not need to recreate the remaining checkout screens.

For custom checkout, continue with the sequence below and support each configured payment-session type your application offers.

3. Set contact and address data

Storefront APIVariables

Code in graphql

This address is illustrative; use appropriate test data for your configured delivery area. Add billing address information where your flow requires it. For an authenticated buyer, derive customer identity from the session rather than trusting an arbitrary submitted ID.

4. Select returned shipping

Storefront APIVariables

Code in graphql

Use a method ID from the latest availableShippingMethods response. The input expects method IDs, not rate IDs or your own shipping prices. Changing address or cart contents can invalidate a previous selection.

5. Initialize an eligible payment method

Query paymentGateways for this cart. Then call cartPaymentSessionInitialize with cartId and gatewayId. Request __typename and the fragments needed by the chosen session type. Complete required provider interaction with the provider’s client integration. Do not equate session initialization with a successful payment.

The Next.js example implements these documents in src/lib/thorcommerce/storefront/mutations/checkout.graphql and the UI under src/features/checkout.

6. Complete and verify

Storefront APIVariables

Code in graphql

Persist the order ID before showing success. Disable duplicate submission while the request is pending. For a lost response, reconcile with the same cart ID using order-placement recovery. Do not start a second purchase because the first request timed out.

Test quantity changes, unavailable stock, address changes, rejected payment, refresh during checkout, and a lost completion response in your test environment. See Recover from storefront errors for the recovery interface.