Cart Overview

The SDK manages the shopping cart lifecycle through the Shopify Storefront GraphQL API. The cart ID is persisted in AsyncStorage so it survives app restarts.

How It Works

First add — calling addLines when no cart exists automatically creates one
Subsequent operations — the stored cart ID is used for all mutations
State sync — each mutation returns the updated cart and updates local state
Clear — removes the cart ID from storage; next add creates a fresh cart

Cart Service vs Hook

	Service	Hook
Access	`useStackfront().cart`	`useCart()`
State	None (imperative)	`cart`, `loading`, `error`
Auto-fetch	No	Yes (fetches on `ready`)
Mutations return updated cart	Yes	Yes + updates state

Cart Shape

The cart response follows Shopify’s Storefront API cart type:

{
  id: string;
  checkoutUrl: string;
  lines: { edges: [{ node: { id, quantity, merchandise } }] };
  cost: { subtotalAmount, totalAmount, totalTaxAmount };
  buyerIdentity: { countryCode, customer, email, phone };
}

See Types Reference for the full schema.