Saleor GraphQL API

Before writing code

Fetch live docs:

1. Fetch https://docs.saleor.io/docs/developer/api-reference for API reference overview
2. Web-search site:docs.saleor.io GraphQL queries mutations examples for query patterns
3. Web-search site:docs.saleor.io cursor pagination first after for pagination reference
4. Web-search site:docs.saleor.io authentication JWT token for auth token handling
5. Web-search site:docs.saleor.io GraphQL error handling for mutation error patterns
6. 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.

Authentication

Token Lifecycle

Tokens are short-lived JWTs. Always use tokenRefresh to obtain new access tokens rather than re-authenticating.

Query Patterns

Product Queries

Order Queries

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:

Pagination Response Structure

Filtering

Saleor provides typed filter input objects for each queryable resource:

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:

Common Error Codes

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:

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:

Code Generation

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.