Usage Flows

Common integration patterns for the Cart v2 APIs.

Paths in the diagrams are relative to the v2 cart base (e.g. /generate -> v2/checkout/generate, /{cart}/items -> v2/checkout/{cart}/items).

Guest Checkout Flow

A visitor browses, adds items, optionally applies a coupon, then checks out without creating an account.

Notes:

identifier_type is one of id, variant_id, sku. identifier is the matching value.

Items are added/updated/removed one at a time; there is no bulk array body.

When a guest signs in mid-session, attach the existing guest cart to the authenticated user so checkout proceeds against the same cart.

Notes:

POST /{cart}/assign requires a Bearer JWT.

Returns 403 forbidden if the cart is already owned by a non-guest user.

Get Cart (refresh state)

Read the current cart at any time with GET /{cart}. By default the response omits the items array; pass include_items=true to include line items.

Error Recovery — Cart no longer available

If a stored cart id can no longer be used (expired, cleared, or not found), generate a new cart and replay the items.

Usage Flows

Usage Flows#

Guest Checkout Flow#

Authenticated User Flow (attach guest cart on sign-in)#

Get Cart (refresh state)#

Error Recovery — Cart no longer available#

Usage Flows

Guest Checkout Flow

Authenticated User Flow (attach guest cart on sign-in)

Get Cart (refresh state)

Error Recovery — Cart no longer available