Cart - Commerce Engine Docs

For most storefronts, use Hosted Checkout. It includes a production cart drawer, item updates, discounts, authentication, addresses, fulfilment, payment, and confirmation. Build a custom cart only when the product requires full control over the cart and checkout UI.

Cart invariants

These rules apply whether the UI is custom or Hosted Checkout:

Every cart belongs to an anonymous or logged-in session.
Commerce Engine does not create an empty cart.
The first item creates the cart.
Later item changes mutate the existing cart.
variant_id is always present in item operations; use null for a simple product.
A mutation returns the full updated cart.
Login merges the active anonymous cart into the account session.
to_be_paid is the final amount to show after loyalty and credit deductions.
Carts can expire and must be recovered gracefully.

Hosted Checkout cart

const { addToCart, cartCount, isReady, openCart } = useCheckout();

<button disabled={!isReady} onClick={() => openCart()}>
  Cart ({cartCount})
</button>

<button
  disabled={!isReady}
  onClick={() => addToCart(productId, variantId, 1)}
>
  Add to cart
</button>

When the application also uses @commercengine/storefront, use provided auth mode and two-way token synchronization. See the framework-specific Hosted Checkout guide.

Custom cart setup

Use the session accessor:

const sdk = storefront.session();

For first-party SSR wrappers, use the browser or request-bound session accessor appropriate to the component or mutation boundary.

Retrieve the active cart

const { data, error, response } = await sdk.cart.getUserCart();

if (response?.status === 404) {
  // Valid state: this session has no active cart yet.
  return null;
}

if (error) throw new Error(error.message);
return data?.cart ?? null;

A missing cart is an empty state, not necessarily an application error.

First Add to Cart

Create the cart with at least one item:

const { data, error } = await sdk.cart.createCart({
  items: [
    {
      product_id: productId,
      variant_id: variantId,
      quantity: 1,
    },
  ],
});

if (error) throw new Error(error.message);
const cart = data?.cart;

For a product with variants, variantId must be the resolved purchasable variant ID. For a simple product it must be null.

Creating the cart on first add

Add, update, and remove items

Use the same operation for subsequent item changes. quantity is the desired total quantity, not a delta.

const { data, error } = await sdk.cart.addDeleteCartItem(
  { id: cartId },
  {
    product_id: productId,
    variant_id: variantId,
    quantity: 3,
  },
);

Remove the line by setting quantity to zero:

await sdk.cart.addDeleteCartItem(
  { id: cartId },
  {
    product_id: productId,
    variant_id: variantId,
    quantity: 0,
  },
);

Always replace local cart state with the updated cart returned by the latest valid mutation.

Serialize cart mutations

Rapid clicks or quantity changes can start multiple mutations concurrently. Because every response contains a complete cart snapshot, an older response can overwrite a newer state. Queue cart mutations with concurrency 1:

let queue: Promise<void> = Promise.resolve();

function enqueueCartMutation(operation: () => Promise<void>) {
  queue = queue.then(operation, operation);
  return queue;
}

function updateQuantity(item: CartItem, quantity: number) {
  return enqueueCartMutation(async () => {
    const currentCart = getCartState();
    if (!currentCart) return;

    const { data, error } = await sdk.cart.addDeleteCartItem(
      { id: currentCart.id },
      {
        product_id: item.product_id,
        variant_id: item.variant_id,
        quantity,
      },
    );

    if (error) throw new Error(error.message);
    if (data?.cart) setCartState(data.cart);
  });
}

A mutation library with an async queue or mutex is preferable for larger applications.

Serialized cart mutations

Optimistic UI

Optimistic updates can improve perceived speed, but they do not remove the need to serialize server mutations. A safe pattern:

calculate and render an optimistic local state
enqueue the server operation
replace local state with the returned cart
roll back or refetch on failure
announce the result for assistive technology

Do not calculate authoritative discounts, tax, shipping, or to_be_paid solely on the client.

Persist and recover cart state

The active cart is tied to the session, so getUserCart() is the preferred recovery path. A custom cart can also persist the last cart_id to reduce lookup ambiguity. On startup or cart open:

read the persisted cart ID if present
fetch that cart
check expires_at
if missing/expired, clear the stored ID
fall back to getUserCart()
create a new cart only when the next item is added

function isExpired(cart: Cart) {
  return Boolean(
    cart.expires_at && new Date(cart.expires_at).getTime() <= Date.now(),
  );
}

Persist the order number after order creation as well, so the payment-return page can recover after navigation or reload.

Restoring the active cart

Commerce Engine merges the active anonymous cart into the logged-in session. After verification:

invalidate/refetch the cart query
do not copy items manually
do not create another cart

If the returning account had a previous active cart, Commerce Engine resolves the active-cart transition server-side.

Logout

Logout returns a new anonymous token pair. Preserve those tokens through managed SDK storage, then refetch cart state. Do not call clearTokens() after a successful logout.

Cart structure

Important fields include:

Field	Use
`cart_items`	Render line items
`cart_items_count`	Unique line count or reported item count, according to contract
`subtotal`	Item amount before later adjustments
`items_tax_amount`	Item tax
`shipping_amount`	Shipping amount
`promotion_discount_amount`	Automatic promotion deduction
`coupon_discount_amount`	Coupon deduction
`loyalty_points_redeemed`	Applied loyalty points
`credit_balance_used`	Applied wallet/store credit
`grand_total`	Total before loyalty/credit deductions
`to_be_paid`	Final amount the customer pays
`expires_at`	Expiry timestamp

Display to_be_paid as the final payable amount. grand_total can be higher when loyalty points or credit balance have been applied.

Render money using the currency information returned by the cart; do not assume one currency symbol.

Coupons and promotions

Automatic promotions are reflected in the returned cart. For a custom coupon UI:

const { data, error } = await sdk.cart.applyCoupon(
  { id: cartId },
  { coupon_code: code.trim() },
);

Remove the coupon:

const { data, error } = await sdk.cart.removeCoupon({ id: cartId });

Some coupons depend on logged-in customer history or groups. An anonymous session can receive an error requiring login. Show the API’s user-safe message or map it to a clear login prompt. Do not assume every available coupon is valid for the current cart until the API applies or evaluates it.

Loyalty and credit balance

Loyalty and credit operations require the appropriate logged-in customer state. After every redemption/removal:

use the returned cart
update to_be_paid
handle the zero-payment case during order creation
do not subtract values twice in the UI

Addresses and fulfilment

Addresses, serviceability, and fulfilment selection change cart totals. Keep them in the custom checkout flow rather than treating the cart shown on the PLP/PDP as final. See Checkout for:

saved address linking
pincode lookup and deliverability
multiple shipments
delivery versus collect-in-store
payment and retry

Cart deletion

Use the exact SDK method contract for deleting a cart and confirm its response semantics. After successful deletion:

clear persisted cart ID
set local cart state to empty
invalidate cart badge/query state

Do not assume a deleted cart remains as an editable empty shell unless the operation contract explicitly says so.

Error handling

Treat errors by operation and status:

Situation	UI response
No active cart / 404 from user-cart lookup	Empty cart
Cart expired	Clear persisted ID; create on next add
Invalid/unavailable variant	Return to PDP selection or remove line
Quantity exceeds availability	Restore server cart and show message
Coupon requires login	Prompt login, preserve cart
Network/5xx failure	Keep local cart visible, offer retry, refetch before checkout
Session failure	Re-establish anonymous session or require login as appropriate

Do not retry cart mutations blindly because the first attempt may have succeeded server-side.

Accessibility

cart count should use aria-live="polite"
quantity controls need accessible names including the product
disable controls while their queued mutation is active
return focus appropriately after removing an item
announce errors and successful updates
maintain keyboard focus when a drawer opens/closes

Hosted Checkout supplies the cart UI; validate its integration and surrounding buttons in the host application.

Production checklist

[ ] no empty-cart creation request
[ ] first item uses createCart
[ ] later changes use the existing cart
[ ] variant_id always supplied or null for simple product
[ ] mutations serialized
[ ] authoritative returned cart replaces local state
[ ] cart ID/session recovery implemented
[ ] expires_at handled
[ ] login merge refetched, not recreated
[ ] logout preserves anonymous tokens
[ ] to_be_paid displayed as final amount
[ ] money uses returned currency
[ ] failed mutations not blindly retried
[ ] keyboard and screen-reader behaviour tested

Cart skills and starter patterns

Use the cart/checkout skill for exact edge cases and the production starters for integrated query, session, and Hosted Checkout patterns.

​Cart invariants

​Hosted Checkout cart

​Custom cart setup

​Retrieve the active cart

​First Add to Cart

​Add, update, and remove items

​Serialize cart mutations

​Optimistic UI

​Persist and recover cart state

​Login and logout transitions

​Login

​Logout

​Cart structure

​Coupons and promotions

​Loyalty and credit balance

​Addresses and fulfilment

​Cart deletion

​Error handling

​Accessibility

​Production checklist

Cart skills and starter patterns

Cart invariants

Hosted Checkout cart

Custom cart setup

Retrieve the active cart

First Add to Cart

Add, update, and remove items

Serialize cart mutations

Optimistic UI

Persist and recover cart state

Login and logout transitions

Login

Logout

Cart structure

Coupons and promotions

Loyalty and credit balance

Addresses and fulfilment

Cart deletion

Error handling

Accessibility

Production checklist