Saleor e-commerce API patterns for building storefronts. Use when working with Saleor's GraphQL API, products, variants, checkout, channels, permissions, or debugging API behavior. Framework-agnostic — applies to any Saleor storefront.

Saleor Storefront Universal guide for building storefronts on the Saleor e commerce platform. Covers the Saleor GraphQL API data model, permission system, checkout lifecycle, channel architecture, and product/variant patterns. Framework agnostic — these rules apply whether you're using Next.js, Remix, Nuxt, or a custom setup. When to Apply Reference these guidelines when: Querying Saleor's GraphQL API for products, categories, or collections Building product detail pages with variant selection Implementing checkout and payment flows Working with multi channel and multi currency setups Debugging "product not purchasable" or permission errors Working with Saleor 3.23+ stock availability modes ( useLegacyShippingZoneStockAvailability ) Investigating Saleor API behavior via source code Rule Categories Priority Category Impact Prefix 1 API CRITICAL api 2 Products HIGH products 3 Checkout HIGH checkout 4 Channels MEDIUM channels Quick Reference 1. API (CRITICAL) api data model — Nullable fields, pricing structure, automatic storefront filtering api permissions — Token types, permission errors, two tier query pattern api graphql patterns — Channel scoped queries, variant attributes, filtering, codegen api investigation — How to investigate Saleor API behavior via types and source 2. Products (HIGH) products variants — Variant model, selection vs non selection attributes, pricing, UX patterns 3. Checkout (HIGH) checkout lifecycle — Session lifecycle, common errors, debugging payment issues 4. Channels (MEDIUM) channels purchasability — Stock availability modes (legacy vs direct, 3.23+), purchasability vs shippability, fulfillment triangle, mode aware checklists, channel scoped queries, stock webhooks How to Use Read individual rule files for detailed explanations and code examples: Each rule file contains: Brief explanation of why it matters Code examples (correct and incorrect patterns) Anti patterns to avoid Full Compiled Document For the complete guide with all rules expanded: AGENTS.md

saleor-storefront