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.

Agent-ask inputs

• Storefront key — ask the user; send it on every Shop request. Never invent it.
• Server URL — ask the user for their Bagisto server's base URL (e.g. https://store.example.com) and prefix every endpoint path with it. Never assume localhost or a demo domain.

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.
• Get Locales · Get Countries (+ country states).

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.
• Theme customizations (hero image carousel, static blocks, featured/category carousels, footer links) — the homepage layout the admin configures. Read with Get Theme Customizations. Each block tells you what to render (a product-carousel block gives you the product ids to fetch; an image block 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=, and category / price / attribute filters.
• Search — Search Products for the search results page.
• Filters (faceting) — Get Attributes and Attribute Options to build the filter sidebar (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

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