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