Cart Workflow (Shop)
Build a cart for a guest or a logged-in customer: create/obtain the cart, add and update items, apply coupons, and merge a guest cart into the customer cart at login.
Prerequisites
- A valid storefront key (Setup, Authentication).
- For the customer path: a logged-in customer (Customer login).
When does a merge happen? A guest adds items to a guest cart, then decides to log in. On login you call mergeCart with the guest cart token — the guest cart's items are merged into the customer's own cart so nothing is lost.
Dependency diagram
Ordered call table
| # | Step | Endpoint | Depends on | Note |
|---|---|---|---|---|
| 1 | Create guest cart | POST create-cart · GraphQL | storefront key | Guest path only; returns a cart token |
| 2 | Customer login | POST login | storefront key | Customer path; after login, merge the guest cart (step 3) |
| 3 | Merge guest cart | POST merge-cart · GraphQL | a guest cart id + a logged-in customer (customer Bearer token) | Merges the guest cart's items into the customer cart so nothing is lost |
| 4 | Add item | POST add-to-cart · GraphQL | cart (guest token or logged-in customer) | Same endpoint for both paths |
| 5 | Update item qty | POST update-cart-item | an item in the cart | |
| 6 | Apply coupon | POST apply-coupon | an item in the cart | Remove with remove-coupon |
| 7 | Read cart | GET get-cart · GraphQL | any cart mutation | Totals, items, applied coupon |
GraphQL equivalents: the table links REST paths. Each step has a GraphQL operation (
createCartToken,createAddProductInCart,createUpdateCartItem,createApplyCoupon,createMergeCart,createReadCart).
End-to-end sequence
- Guest: create-cart → add-to-cart → apply-coupon → get-cart.
- Guest who then logs in: create-cart (guest) → add-to-cart → login → merge-cart → get-cart.
Follow each linked endpoint page for the exact request / response body.
Customize
Every call below links to its REST endpoint page for concreteness. The sequence is transport-agnostic — the same flow works over GraphQL with the equivalent query or mutation, and each REST page cross-links to its GraphQL twin. Pick whichever transport your client uses; only the request shape changes, never the order of steps.
To change cart behavior on the server, see Customization → Shop.