Build a storefront on the Bagisto Shop API

/api/shop/*

POST /api/graphql

⚠️ Load these FIRST (before any code)

1. reference/connecting-to-the-api.md

   — auth (storefront key + cart/customer tokens), the

   {data,meta}

   /header pagination, error codes, and the verify-before-coding protocol.

2. reference/graphql.md

   — if the client picked GraphQL: the result-field/

   id

   rule, camelCase inputs, cursor pagination.

https://api-docs.bagisto.com

/llms.txt

Step 1 — ask the client (CRITICAL, before building)

1. Platform — web, mobile (native/cross-platform), desktop?
2. Framework/stack — React/Next, Vue/Nuxt, Flutter, React Native, Swift/Kotlin, plain JS?
3. Transport — REST or GraphQL? (REST for simple screens; GraphQL when a screen needs many related fields at once. Both fully supported.)
4. First feature/flow — catalog, cart+checkout, account, …?

Step 2 — open the reference for the feature

Flows (multi-step journeys / pages)

reference/flows/product-listing.md

reference/flows/product-details.md

reference/flows/add-to-cart.md

reference/flows/cart.md

reference/flows/checkout.md

reference/flows/order-confirmation.md

reference/flows/authentication.md

reference/flows/account.md

reference/flows/customer-orders.md

Features (single capabilities)

reference/features/coupons.md

reference/features/wishlist.md

reference/features/compare.md

reference/features/reviews.md

reference/features/newsletter.md

reference/features/contact-us.md

reference/features/storefront-context.md

Consolidated critical rules (the gotchas that bite)

• Verify before coding. PAUSE → open the endpoint's docs page (or query the MCP) → confirm the method/fields → implement → check types. Don't guess endpoint names or bodies.
• Auth per surface. Every shop call sends

  X-STOREFRONT-KEY

  ; cart/account/checkout calls also send

  Authorization: Bearer <cartToken | customerToken>

  . Guests mint a cart token first (

  POST /api/shop/cart-tokens

  ).
• Mutating cart/checkout calls return the full updated cart — reconcile your UI from the response, don't mutate locally.
• Guest→customer merge on login (

  merge-carts

  ) or the guest's items are lost.
• Post-order cleanup — clear cart state + discard the guest cart token after a placed order, or the cart popup shows stale items.
• GraphQL: select the documented result fields of action mutations (

  success

  /

  message

  /

  orderId

  /totals), not a generic

  id

  ; inputs are camelCase; one field per line. See

  reference/graphql.md

  .
• Don't hardcode dynamic data (shipping/payment methods, prices, options) — fetch it from the API.