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 filteringapi-permissions — Token types, permission errors, two-tier query patternapi-graphql-patterns — Channel-scoped queries, variant attributes, filtering, codegenapi-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:
rules/api-data-model.md
rules/products-variants.md
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
1---2name: saleor-storefront3description: 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.4license: MIT5---6
7# Saleor Storefront
8
9Universal guide for building storefronts on the Saleor e-commerce platform. Covers
10the Saleor GraphQL API data model, permission system, checkout lifecycle, channel
11architecture, and product/variant patterns. Framework-agnostic — these rules apply
12whether you're using Next.js, Remix, Nuxt, or a custom setup.
13
14## When to Apply
15
16Reference these guidelines when:
17
18- Querying Saleor's GraphQL API for products, categories, or collections
19- Building product detail pages with variant selection
20- Implementing checkout and payment flows
21- Working with multi-channel and multi-currency setups
22- Debugging "product not purchasable" or permission errors
23- Working with Saleor 3.23+ stock availability modes (`useLegacyShippingZoneStockAvailability`)
24- Investigating Saleor API behavior via source code
25
26## Rule Categories
27
28| Priority | Category | Impact | Prefix |
29| -------- | --------- | -------- | ------------ |
30| 1 | API | CRITICAL | `api-` |
31| 2 | Products | HIGH | `products-` |
32| 3 | Checkout | HIGH | `checkout-` |
33| 4 | Channels | MEDIUM | `channels-` |
34
35## Quick Reference
36
37### 1. API (CRITICAL)
38
39- `api-data-model` — Nullable fields, pricing structure, automatic storefront filtering
40- `api-permissions` — Token types, permission errors, two-tier query pattern
41- `api-graphql-patterns` — Channel-scoped queries, variant attributes, filtering, codegen
42- `api-investigation` — How to investigate Saleor API behavior via types and source
43
44### 2. Products (HIGH)
45
46- `products-variants` — Variant model, selection vs non-selection attributes, pricing, UX patterns
47
48### 3. Checkout (HIGH)
49
50- `checkout-lifecycle` — Session lifecycle, common errors, debugging payment issues
51
52### 4. Channels (MEDIUM)
53
54- `channels-purchasability` — Stock availability modes (legacy vs direct, 3.23+), purchasability vs shippability, fulfillment triangle, mode-aware checklists, channel-scoped queries, stock webhooks
55
56## How to Use
57
58Read individual rule files for detailed explanations and code examples:
59
60```
61rules/api-data-model.md
62rules/products-variants.md
63```
64
65Each rule file contains:
66
67- Brief explanation of why it matters
68- Code examples (correct and incorrect patterns)
69- Anti-patterns to avoid
70
71## Full Compiled Document
72
73For the complete guide with all rules expanded: `AGENTS.md`
saleor