Build a Storefront

The complete storefront blueprint — every screen a shopper sees and the Shop API behind it, from the homepage to a placed order and the customer account. Use this as the map; for the two deepest flows, the focused Cart and Checkout workflow pages carry the step-by-step call sequence.

Every request carries the X-STOREFRONT-KEY header; customer-scoped steps also carry Authorization: Bearer <token>. Open each linked page for the exact request/response shape.

0. Context (locale / currency / channel)

Optional per-request headers X-LOCALE, X-CURRENCY, X-CHANNEL control what content the API returns. Discover valid values:

• Get Channels — the store's sales channels; each channel lists its allowed currencies and locales.
• Get Locales — available languages (with direction for RTL).

1. Homepage

The landing screen is built from admin-managed content, not just products:

• CMS pages (About, Privacy, Terms, custom landing copy) — the admin authors these; the storefront reads them via the CMS Pages query (GraphQL). Render them as static pages and footer links.
• Sections (hero image carousel, static blocks, featured/category carousels, footer links) — the homepage layout the merchandiser arranges. Read with List Sections. Each section tells you what to render (a product-carousel section gives you the product ids to fetch; an image section gives banners).
• Navigation — Get Categories for the menu, or Category Tree for a nested megamenu.

2. Catalog

• Category page — Get Categories for the category, then list its products (step below) filtered by that category.
• Product listing — Get Products, paginated with ?page=, ?per_page=, ?sort=. Scope and filter it with ?category_id=, ?price=10,200 (min,max), ?new=1, ?featured=1, ?type=, and any attribute code (?color=3&size=6). The complete parameter list is on Search Products.
• Category children — ?parent_id=N (REST) or treeCategories(parentId: N) (GraphQL). The GraphQL categories field has no parentId argument.
• Search — Search Products — the same endpoint with ?query=; composes with the filters above.
• Filters (faceting sidebar) — Get Attributes (isFilterable: 1) and Attribute Options give you the filter codes and option ids to feed the product-listing filters above (color, size, brand, price).
• Product detail page — Get Product for a single product: price, images, description, and type-specific data. Configurable / bundle / grouped / downloadable products expose their extra structure via product sub-resources and type sub-resources; bookable products via booking slots.
• Product reviews — show and collect ratings: Get Product Reviews · Create Product Review (logged-in customer).

3. Shopper engagement

• Wishlist (logged-in) — List · Add / Toggle · Move to Cart.
• Compare — List · Add · Remove.
• Newsletter — Subscribe.

4. Authenticate the customer

For cart-to-order and the account area, log the customer in and keep the token:

• Customer Login → data.token → send as Authorization: Bearer <token>.
• New customers: Customer Registration.
• Guests can still order without an account — see the Cart workflow's guest path.

5. Cart

The full cart sequence (guest / customer, add / update, coupons, merge on login) is its own page: Cart workflow →.

6. Checkout

The enforced checkout sequence (addresses → shipping → payment methods → place order, with saved-address reuse) is its own page: Checkout workflow →.

7. Customer account (post-login)

• Profile & addresses — the Customers endpoints: addresses, change password.
• Orders — Get Customer Orders · single order for the confirmation + history screens.
• Invoices — Get Customer Invoices · download PDF.
• Downloadable products — Get Downloadable Products.
• GDPR — raise / list / revoke data requests (config-gated).

GraphQL variant

Every step has a GraphQL equivalent at POST /api/graphql (see the Shop GraphQL section). On cart / checkout mutations select the result fields (cart contents, order id, success, message) — they're actions, so don't select an id on them.

Status codes to handle

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.

200/201 success · 401 unauthenticated (missing key/token) · 403 forbidden · 400 bad input · 404 not found · 422 validation (e.g. quantity exceeds stock).