# saleor-storefront

Patterns for Saleor's GraphQL API in storefronts, covering products, variants, checkout, channels and permissions.

Skill by Saleor. Category: Web and browsers.

## Install

Project (for this project only):

```sh
npx skills add saleor/agent-skills --skill saleor-storefront
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add saleor/agent-skills --skill saleor-storefront -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Warn
- Runlayer: Warn

Installs: 2240. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/saleor/agent-skills/saleor-storefront)

## Source

[Open the source](https://github.com/saleor/agent-skills/tree/HEAD/skills/saleor-storefront). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: saleor-storefront
description: >
  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.
license: MIT
metadata:
  author: saleor
  version: "1.0.0"
---

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

- Previous: [connector-quickbooks](https://syn4pse.dev/terminal/caffeine-connector-quickbooks.md)
- Next: [writing-motoko](https://syn4pse.dev/terminal/writing-motoko.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
