Saleor GraphQL API
Before writing code
Fetch live docs:
- Fetch
https://docs.saleor.io/docs/developer/api-reference for API reference overview
- Web-search
site:docs.saleor.io GraphQL queries mutations examples for query patterns
- Web-search
site:docs.saleor.io cursor pagination first after for pagination reference
- Web-search
site:docs.saleor.io authentication JWT token for auth token handling
- Web-search
site:docs.saleor.io GraphQL error handling for mutation error patterns
- Fetch
https://docs.saleor.io/docs/developer/api-conventions for API conventions
GraphQL-First Architecture
Saleor exposes its entire functionality through a single GraphQL endpoint. There is no REST API -- all interactions (storefront, dashboard, apps, integrations) use GraphQL exclusively.
| Aspect |
Detail |
| Endpoint |
/graphql/ |
| Protocol |
HTTP POST with JSON body |
| Introspection |
Enabled by default (disable in production if needed) |
| Playground |
Available at the API URL in browser |
| Schema |
Single unified schema for all consumers |
Authentication
| Method |
Use Case |
Header |
| JWT (Staff) |
Dashboard operations, admin mutations |
Authorization: Bearer <token> |
| JWT (Customer) |
Storefront customer actions |
Authorization: Bearer <token> |
| App Token |
App-to-Saleor API calls |
Authorization: Bearer <app-token> |
| No Auth |
Public storefront queries (products, collections) |
None required |
Token Lifecycle
| Operation |
Mutation |
| Staff login |
tokenCreate(email, password) |
| Customer login |
tokenCreate(email, password) |
| Refresh token |
tokenRefresh(refreshToken) |
| Verify token |
tokenVerify(token) |
Tokens are short-lived JWTs. Always use tokenRefresh to obtain new access tokens rather than re-authenticating.
Query Patterns
Product Queries
| Query |
Purpose |
products(first, after, filter, channel) |
List products with pagination |
product(id, slug, channel) |
Single product by ID or slug |
categories(first, after, filter) |
List categories |
collections(first, after, filter, channel) |
List collections |
Order Queries
| Query |
Purpose |
orders(first, after, filter) |
List orders (staff) |
order(id) |
Single order detail |
me { orders } |
Customer's own orders |
draftOrders(first, after) |
List draft orders (staff) |
Channel Scoping
Most storefront queries require a channel argument to scope results:
query Products($channel: String!) {
products(first: 10, channel: $channel) {
edges { node { id name pricing { ... } } }
}
}
Queries without a channel argument return data across all channels (staff only).
Cursor-Based Pagination
Saleor uses Relay-style cursor pagination throughout its API:
| Parameter |
Type |
Purpose |
first |
Int |
Number of items from the start |
after |
String |
Cursor to paginate forward |
last |
Int |
Number of items from the end |
before |
String |
Cursor to paginate backward |
Pagination Response Structure
| Field |
Purpose |
edges[].node |
The actual data object |
edges[].cursor |
Opaque cursor for this edge |
pageInfo.hasNextPage |
Whether more items exist forward |
pageInfo.hasPreviousPage |
Whether more items exist backward |
pageInfo.startCursor |
Cursor of the first edge |
pageInfo.endCursor |
Cursor of the last edge |
totalCount |
Total number of matching items |
Filtering
Saleor provides typed filter input objects for each queryable resource:
| Filter Input |
Key Fields |
ProductFilterInput |
search, price, categories, collections, productTypes, isPublished |
OrderFilterInput |
created, status, customer, paymentStatus |
CustomerFilterInput |
search, dateJoined, numberOfOrders |
Filters are passed as the filter argument on list queries.
Mutations and Error Handling
Saleor mutations return the result alongside an errors array in the response:
| Field |
Purpose |
<entity> |
The created/updated object on success |
errors |
Array of { field, message, code } on failure |
Common Error Codes
| Code |
Meaning |
REQUIRED |
A required field is missing |
INVALID |
Field value is invalid |
NOT_FOUND |
Referenced object does not exist |
UNIQUE |
Value violates a uniqueness constraint |
GRAPHQL_ERROR |
General GraphQL execution error |
Always check the errors array -- a mutation may return HTTP 200 with validation errors in the response body.
Subscriptions
Saleor supports GraphQL subscriptions for real-time webhook payloads:
| Aspect |
Detail |
| Transport |
Webhook POST (not WebSocket) |
| Definition |
Subscription query defines the payload shape |
| Registration |
Via App manifest or webhookCreate mutation |
| Use Case |
Custom webhook payloads with only the fields you need |
Subscription queries are attached to webhook configurations to define exactly which fields are delivered in the payload.
GraphQL Playground
The built-in Playground is available at the API endpoint URL in a browser:
| Feature |
Detail |
| Schema explorer |
Browse all types, queries, mutations |
| Query editor |
Write and execute queries with autocomplete |
| Auth header |
Add Authorization: Bearer <token> in HTTP Headers panel |
| History |
Previously executed queries are saved |
| Docs panel |
Inline documentation for all fields |
Code Generation
| Tool |
Purpose |
graphql-codegen |
Generate TypeScript types from Saleor schema |
@graphql-codegen/typed-document-node |
Typed document nodes for queries |
@graphql-codegen/introspection |
Generate introspection JSON |
Codegen Configuration
# codegen.yml — Fetch live docs for current config shape
schema: "https://your-saleor-instance.com/graphql/"
documents: "src/**/*.graphql"
generates:
src/generated/graphql.ts:
plugins:
- typescript
- typescript-operations
Best Practices
- Always scope storefront queries with the
channel argument
- Use cursor pagination (
first/after) -- never request unbounded lists
- Check the
errors array on every mutation response, even on HTTP 200
- Use
tokenRefresh to renew JWTs instead of storing long-lived tokens
- Define only the fields you need in queries to minimize response size
- Use GraphQL code generation for type safety in TypeScript projects
- Leverage subscription queries for webhook payloads to get exactly the data shape you need
Fetch the Saleor GraphQL API documentation for exact query signatures, filter input types, and mutation patterns before implementing.
1---2name: saleor-graphql3description: Work with the Saleor GraphQL API — queries, mutations, subscriptions, cursor pagination, filters, error handling, GraphQL Playground, and code generation. Use when building against the Saleor API.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/saleor-graphql7---89# Saleor GraphQL API1011## Before writing code1213**Fetch live docs**:141. Fetch `https://docs.saleor.io/docs/developer/api-reference` for API reference overview152. Web-search `site:docs.saleor.io GraphQL queries mutations examples` for query patterns163. Web-search `site:docs.saleor.io cursor pagination first after` for pagination reference174. Web-search `site:docs.saleor.io authentication JWT token` for auth token handling185. Web-search `site:docs.saleor.io GraphQL error handling` for mutation error patterns196. Fetch `https://docs.saleor.io/docs/developer/api-conventions` for API conventions2021## GraphQL-First Architecture2223Saleor exposes its entire functionality through a single GraphQL endpoint. There is no REST API -- all interactions (storefront, dashboard, apps, integrations) use GraphQL exclusively.2425| Aspect | Detail |26|--------|--------|27| Endpoint | `/graphql/` |28| Protocol | HTTP POST with JSON body |29| Introspection | Enabled by default (disable in production if needed) |30| Playground | Available at the API URL in browser |31| Schema | Single unified schema for all consumers |3233## Authentication3435| Method | Use Case | Header |36|--------|----------|--------|37| JWT (Staff) | Dashboard operations, admin mutations | `Authorization: Bearer <token>` |38| JWT (Customer) | Storefront customer actions | `Authorization: Bearer <token>` |39| App Token | App-to-Saleor API calls | `Authorization: Bearer <app-token>` |40| No Auth | Public storefront queries (products, collections) | None required |4142### Token Lifecycle4344| Operation | Mutation |45|-----------|---------|46| Staff login | `tokenCreate(email, password)` |47| Customer login | `tokenCreate(email, password)` |48| Refresh token | `tokenRefresh(refreshToken)` |49| Verify token | `tokenVerify(token)` |5051Tokens are short-lived JWTs. Always use `tokenRefresh` to obtain new access tokens rather than re-authenticating.5253## Query Patterns5455### Product Queries5657| Query | Purpose |58|-------|---------|59| `products(first, after, filter, channel)` | List products with pagination |60| `product(id, slug, channel)` | Single product by ID or slug |61| `categories(first, after, filter)` | List categories |62| `collections(first, after, filter, channel)` | List collections |6364### Order Queries6566| Query | Purpose |67|-------|---------|68| `orders(first, after, filter)` | List orders (staff) |69| `order(id)` | Single order detail |70| `me { orders }` | Customer's own orders |71| `draftOrders(first, after)` | List draft orders (staff) |7273### Channel Scoping7475Most storefront queries require a `channel` argument to scope results:7677```graphql78query Products($channel: String!) {79 products(first: 10, channel: $channel) {80 edges { node { id name pricing { ... } } }81 }82}83```8485Queries without a channel argument return data across all channels (staff only).8687## Cursor-Based Pagination8889Saleor uses Relay-style cursor pagination throughout its API:9091| Parameter | Type | Purpose |92|-----------|------|---------|93| `first` | Int | Number of items from the start |94| `after` | String | Cursor to paginate forward |95| `last` | Int | Number of items from the end |96| `before` | String | Cursor to paginate backward |9798### Pagination Response Structure99100| Field | Purpose |101|-------|---------|102| `edges[].node` | The actual data object |103| `edges[].cursor` | Opaque cursor for this edge |104| `pageInfo.hasNextPage` | Whether more items exist forward |105| `pageInfo.hasPreviousPage` | Whether more items exist backward |106| `pageInfo.startCursor` | Cursor of the first edge |107| `pageInfo.endCursor` | Cursor of the last edge |108| `totalCount` | Total number of matching items |109110## Filtering111112Saleor provides typed filter input objects for each queryable resource:113114| Filter Input | Key Fields |115|-------------|-----------|116| `ProductFilterInput` | `search`, `price`, `categories`, `collections`, `productTypes`, `isPublished` |117| `OrderFilterInput` | `created`, `status`, `customer`, `paymentStatus` |118| `CustomerFilterInput` | `search`, `dateJoined`, `numberOfOrders` |119120Filters are passed as the `filter` argument on list queries.121122## Mutations and Error Handling123124Saleor mutations return the result alongside an `errors` array in the response:125126| Field | Purpose |127|-------|---------|128| `<entity>` | The created/updated object on success |129| `errors` | Array of `{ field, message, code }` on failure |130131### Common Error Codes132133| Code | Meaning |134|------|---------|135| `REQUIRED` | A required field is missing |136| `INVALID` | Field value is invalid |137| `NOT_FOUND` | Referenced object does not exist |138| `UNIQUE` | Value violates a uniqueness constraint |139| `GRAPHQL_ERROR` | General GraphQL execution error |140141Always check the `errors` array -- a mutation may return HTTP 200 with validation errors in the response body.142143## Subscriptions144145Saleor supports GraphQL subscriptions for real-time webhook payloads:146147| Aspect | Detail |148|--------|--------|149| Transport | Webhook POST (not WebSocket) |150| Definition | Subscription query defines the payload shape |151| Registration | Via App manifest or `webhookCreate` mutation |152| Use Case | Custom webhook payloads with only the fields you need |153154Subscription queries are attached to webhook configurations to define exactly which fields are delivered in the payload.155156## GraphQL Playground157158The built-in Playground is available at the API endpoint URL in a browser:159160| Feature | Detail |161|---------|--------|162| Schema explorer | Browse all types, queries, mutations |163| Query editor | Write and execute queries with autocomplete |164| Auth header | Add `Authorization: Bearer <token>` in HTTP Headers panel |165| History | Previously executed queries are saved |166| Docs panel | Inline documentation for all fields |167168## Code Generation169170| Tool | Purpose |171|------|---------|172| `graphql-codegen` | Generate TypeScript types from Saleor schema |173| `@graphql-codegen/typed-document-node` | Typed document nodes for queries |174| `@graphql-codegen/introspection` | Generate introspection JSON |175176### Codegen Configuration177178```yaml179# codegen.yml — Fetch live docs for current config shape180schema: "https://your-saleor-instance.com/graphql/"181documents: "src/**/*.graphql"182generates:183 src/generated/graphql.ts:184 plugins:185 - typescript186 - typescript-operations187```188189## Best Practices190191- Always scope storefront queries with the `channel` argument192- Use cursor pagination (`first`/`after`) -- never request unbounded lists193- Check the `errors` array on every mutation response, even on HTTP 200194- Use `tokenRefresh` to renew JWTs instead of storing long-lived tokens195- Define only the fields you need in queries to minimize response size196- Use GraphQL code generation for type safety in TypeScript projects197- Leverage subscription queries for webhook payloads to get exactly the data shape you need198199Fetch the Saleor GraphQL API documentation for exact query signatures, filter input types, and mutation patterns before implementing.