# Saleor Storefront

> Saleor e-commerce API patterns for building storefronts.

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.

- Page: https://ss33.ai/skills/saleor/saleor-storefront-74993840694
- Publisher: saleor
- Category: [Software Development](https://ss33.ai/skills/category/software-development-t44z8z) › [APIs & backend](https://ss33.ai/skills/category/software-development-t44z8z/apis-and-backend-t0x840)
- License: MIT
- Source: https://github.com/saleor/agent-skills/blob/fb1a57255f58950962f6e474ccba1cade40f5163/skills/saleor-storefront/SKILL.md

## Skill

SKILL.md: https://ss33.ai/api/v1/ss33/download/saleor/saleor-storefront-74993840694

# 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`