Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
Figure out what the user actually needs before diving in:
- Goal — building/debugging a GraphQL integration, reacting to a commerce event via webhooks, building a Saleor App/dashboard extension, self-hosting, choosing self-host vs Saleor Cloud, or a checkout/conversion question?
- Surface — the GraphQL API (single
/graphql/endpoint), webhooks (sync + async, 160+ events), the Apps framework (App SDK / dashboard extensions), the Auth SDK (storefront), the Configurator CLI, or the Dashboard UI? - Actor — a User (short-lived JWT from
tokenCreate) or an App (long-lived token, machine-to-machine)? Many mutations (e.g.orderCreateFromCheckout) require an app token, not a user token. - Hosting — self-hosted (own infra: Postgres + Redis/Celery + Django) or Saleor Cloud (Sandbox / Select / Volume / Enterprise)?
Skip-ahead rule: if the prompt already says what they need, go straight to Step 2.
Step 2 — Route or answer directly
If the question is really a cross-platform strategy, hand off with the exact command:
| If the user wants… | Route to |
|---|---|
| Checkout conversion / order bumps / cart-abandonment tactics across carts | /sales-checkout {question} |
| Whether to use a Merchant of Record for global VAT/sales tax | /sales-merchant-of-record {question} |
| Comparing Saleor against another commerce backend | /sales-checkout {question} (platform selection) |
| Post-purchase email / abandoned-cart sequences | /sales-email-marketing {question} |
Otherwise it's a Saleor-specific question — answer it here.
Step 3 — Saleor platform reference
Read references/platform-guide.md for the full reference — capabilities and what's API vs webhook vs UI-only, pricing/plan gates, the data model with JSON/GraphQL shapes, and quick-start recipes. For raw auth/endpoint/webhook/signature detail, read references/saleor-api-reference.md.
Answer using only the relevant section — don't dump the whole guide.
Step 4 — Actionable guidance
- Everything is one GraphQL endpoint. There is no REST surface — read/write via
https://{your-store}.saleor.cloud/graphql/(Cloud) orhttp://localhost:8000/graphql/(self-host). Public product reads need no token; mutations need a token. Use the network inspector / API playground in the Dashboard to build queries. - Pick the right actor + token. Users authenticate with
tokenCreate(email, password)and get a short-lived access token + a refresh token (RS256-signed JWT); refresh withtokenRefresh. Apps get a long-lived token at install/creation for server-to-server work. Send either asAuthorization: Bearer <token>(orAuthorization: JWT <token>). Verify tokens against the JWKS at/.well-known/jwks.jsonor viatokenVerify. - Checkout is a multi-step mutation flow, keyed by variant.
checkoutCreatetakes variant IDs (not product IDs — variants carry inventory + price) and achannel; thencheckoutEmailUpdate,checkoutShippingAddressUpdate/checkoutBillingAddressUpdate,checkoutDeliveryMethodUpdate, a payment/transaction step, and finallyorderCreateFromCheckout(requires an app token) →orderMarkAsPaid. - Saleor HAS native outbound webhooks (unlike Medusa). Register them on an App, choose sync (blocks the request — taxes, shipping, payment) or async (fires after, e.g.
ORDER_CREATED), and shape the payload with a GraphQLsubscription. Verify theSaleor-Signature: default is JWS RS256 (detached payload) verified via JWKS; HMAC SHA-256 is deprecated and only used when asecretKeywas set. Always verify against the raw request body, never a re-serialized object. - Self-host is free; Cloud is for not running infra. Saleor Core is BSD-3 / open-source with no per-sale fee when self-hosted. The
saleor-platformrepo is dev-only — production needs Postgres, Redis (Celery worker + beat), the Core Dockerfile (which is production-ready), and realALLOWED_HOSTS/secrets. Saleor Cloud sells managed infra: Sandbox is free but non-commercial; commercial Cloud starts at Select ~$1,599/mo.
If you discover a gotcha or fix not in references/learnings.md, append it there with today's date.
Gotchas
Best-effort from research (2026-06) — re-verify plan gates, fees, auth, webhook-signature behavior, and API shapes against live docs.
- HMAC webhook signatures are deprecated. New webhooks default to JWS RS256 with a detached payload (verify with the public key from
/.well-known/jwks.json). Only webhooks that had asecretKeyset use HMAC SHA-256 — and that path is deprecated. Code that assumes a simple HMAC header will silently fail to verify JWS-signed events. - Verify the raw body, not a parsed object. Both JWS and HMAC verification require the exact raw request bytes. In Next.js you must disable
bodyParser; re-serializing JSON breaks the signature. orderCreateFromCheckoutneeds an app token, not a user token. Converting a checkout to an order is an app-permissioned mutation — a customer/user JWT will hit anAUTHENTICATED_APP/permission error.saleor-platformis not production. That docker-compose repo is for local development only; deploying it as-is is a common mistake. Use the Core Dockerfile and provision Postgres/Redis/Celery yourself (or use Saleor Cloud).- "Invalid host header" / blank storefront usually means
ALLOWED_HOSTSisn't set correctly for your domain (Django setting) — set it via env, not only in the Dockerfile. - Sandbox is non-commercial. The free Cloud tier is for prototyping; you cannot run a real store on it. Commercial Cloud starts at Select (~$1,599/mo) — for low budgets, self-host instead.
- Sync webhooks are on the critical path. A slow/failing synchronous webhook (tax, shipping, payment) delays or breaks the originating request — there's a ~20s total round-trip cap (2s connect + 18s response). Keep sync handlers fast; use async for side-effects.
- Not a Merchant of Record. Saleor doesn't remit your sales tax/VAT — you own compliance (wire a tax app like Avalara/TaxJar via the tax webhooks, or use a MoR upstream). See
/sales-merchant-of-record.
Related skills
/sales-checkout— Checkout-conversion strategy across carts (order bumps, upsells, cart-abandonment recovery) and platform selection./sales-medusa— The other dev-favorite open-source headless engine (Node.js/REST); compare if you're choosing between self-hostable backends. Medusa has no native outbound webhooks; Saleor does./sales-spree— Open-source (BSD-3) headless engine on Ruby on Rails with REST APIs and native outbound webhooks; compare by stack (Ruby vs Python) and API style (REST vs Saleor's GraphQL)./sales-shopify— The leading hosted commerce backend; compare against Saleor's open-source/self-hosted model./sales-bigcommerce— API-first open-SaaS backend; another platform-selection comparison point./sales-merchant-of-record— Whether to use a MoR (Paddle, Lemon Squeezy) for global tax instead of self-managing (Saleor is not a MoR)./sales-do— Not sure which skill to use? The router matches any sales objective to the right skill. Install:npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: Verify a Saleor webhook signature (developer/automation)
User: "My Saleor ORDER_CREATED webhook handler keeps rejecting the signature even though the secret matches. What am I doing wrong?"
Approach: Check whether the webhook actually uses HMAC at all — Saleor defaults to JWS RS256 (detached payload) and only uses HMAC SHA-256 when a secretKey was set (and that path is deprecated). If no secret is configured, you must verify the Saleor-Signature as a JWS: fetch the public key from https://<domain>/.well-known/jwks.json, then verify with jose.flattenedVerify() using the raw request body as the detached payload. The most common bug is verifying against parsed/re-serialized JSON instead of the raw bytes — in Next.js, disable bodyParser so you can read the raw string. For Saleor Apps, prefer withWebhookSignatureVerified() from @saleor/app-sdk, which handles both paths.
Example 2: Pull all orders into a warehouse via the GraphQL API (developer/automation)
User: "I'm writing a script to export every Saleor order into BigQuery. What auth do I use and how do I paginate?"
Approach: Use an App token (long-lived, machine-to-machine) sent as Authorization: Bearer <app-token> to the single /graphql/ endpoint — create the app and grant MANAGE_ORDERS. Query orders(first: 100, after: $cursor) and page with Relay-style cursor pagination: read pageInfo { hasNextPage endCursor } and pass endCursor as after until hasNextPage is false. Select only the fields you need (orders are deep objects). Note many list queries are channel-scoped, so filter by channel where relevant, and throttle politely (Cloud applies request limits).
Example 3: Self-host vs Saleor Cloud
User: "I'm a solo founder. Should I self-host Saleor or pay for Saleor Cloud?"
Approach: Saleor Core is BSD-3/free with no per-sale fee if you self-host — but it's a real Django app needing Postgres + Redis (Celery worker + beat) and ops (upgrades, scaling, backups). The saleor-platform repo is dev-only; production means the Core Dockerfile + provisioned infra (Railway/Render/Fly/K8s). Saleor Cloud Sandbox is free but non-commercial, and commercial Cloud starts at Select (~$1,599/mo, up to $200k GMV) — steep for a solo founder. Recommendation: if they're comfortable running Django/Postgres/Redis, self-host (cheapest, full control); if their budget is tiny and they want zero ops but Cloud is too pricey, point them to a simpler hosted backend or a drop-in cart instead, and reserve Saleor Cloud for once GMV justifies it.
Troubleshooting
"My webhook signature won't verify"
Confirm the signature scheme first. Saleor's Saleor-Signature is a JWS (RS256, detached payload) by default — verify it with the public key from /.well-known/jwks.json against the raw body. HMAC SHA-256 is only used (and is deprecated) when the webhook had a secretKey; verify that with echo -n "<raw-body>" | openssl dgst -sha256 -hmac "<secret>". The usual failure is verifying parsed JSON instead of the raw request bytes (disable bodyParser in Next.js), or assuming HMAC when the webhook is actually JWS-signed.
"I get AUTHENTICATED_APP or a permission error on a mutation"
The mutation requires an App token with the right permission, not a user token — e.g. orderCreateFromCheckout, order/fulfillment, and most management mutations are app-permissioned. Create an App, grant it the needed permission (MANAGE_ORDERS, MANAGE_PRODUCTS, …), and send its long-lived token as Authorization: Bearer. Also confirm the token isn't expired (refresh user tokens with tokenRefresh).
"My storefront returns 'Invalid host header' or a blank page after deploy"
That's Django's ALLOWED_HOSTS rejecting the request host. Set ALLOWED_HOSTS to include your real domain via environment/runtime config (setting it only in the Dockerfile often doesn't take effect). Also remember the saleor-platform compose repo is development-only — don't deploy it to production; use the Core Dockerfile with proper env, Postgres, and Redis/Celery.