Saleor Development

Overview

Saleor is a headless, GraphQL-first e-commerce platform built on Django and Python. It exposes a fully typed GraphQL API for storefronts and third-party apps, a React-based dashboard for store management, and an extension system that lets you react to events via webhooks or inject UI into the dashboard. This skill covers querying the Saleor API, building Saleor Apps (plugins hosted outside Saleor), and customizing the dashboard with App Extensions.

When to Use This Skill

When building a custom storefront (Next.js, Remix, mobile) against a Saleor backend
When creating a Saleor App that reacts to order or product lifecycle webhooks
When injecting custom UI panels into the Saleor Dashboard via App Extensions
When exploring or extending the Saleor product catalog, checkout, or customer APIs
When setting up a local Saleor development environment with Docker

Prerequisites & Platform Notes

This skill is written for custom/headless storefronts (Node.js, Python, or similar backend). The code examples use TypeScript/Node.js and can be adapted to any stack.

Shopify: Shopify Hydrogen is Shopify's headless framework. MACH/composable patterns apply when using Shopify as the commerce backend with a custom frontend, or when mixing Shopify with other best-of-breed services. WooCommerce: WooCommerce can serve as a headless backend via its REST API and WPGraphQL. These patterns apply when decoupling the frontend from WordPress. Magento: Magento's GraphQL API and PWA Studio support headless architectures. These composable patterns apply to Magento as a backend service in a MACH stack.

You'll need:

Node.js 18+ (or adapt to your backend language)
PostgreSQL (or your preferred relational database)
Redis for caching/queues
Stripe account and API keys
An email sending service (SendGrid, AWS SES, or Postmark)
Docker and/or Kubernetes for container orchestration
CDN (Cloudflare, CloudFront, or Fastly)

Core Instructions

Run Saleor locally with Docker Compose

git clone https://github.com/saleor/saleor-platform.git
cd saleor-platform
docker compose up --detach
# API:       http://localhost:8000/graphql/
# Dashboard: http://localhost:9000

Create the first superuser and populate demo data:

docker compose run --rm api python manage.py createsuperuser
docker compose run --rm api python manage.py populatedb --createsuperuser

Query the Storefront GraphQL API

Use the Saleor CLI or any GraphQL client (Apollo, urql, graphql-request).

Install the CLI for code generation:

npm install -g @saleor/cli
saleor configure

Example — fetch the first 12 products from the default channel:

query ProductList($channel: String!) {
  products(first: 12, channel: $channel) {
    edges {
      node {
        id
        name
        slug
        thumbnail { url alt }
        pricing {
          priceRange {
            start { gross { amount currency } }
          }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

import { createClient } from 'urql';

const client = createClient({
  url: process.env.NEXT_PUBLIC_SALEOR_API_URL,
  fetchOptions: () => ({
    headers: { 'Content-Type': 'application/json' },
  }),
});

const { data } = await client.query(PRODUCT_LIST_QUERY, { channel: 'default-channel' }).toPromise();

Authenticate a customer and start checkout

mutation CustomerLogin($email: String!, $password: String!) {
  tokenCreate(email: $email, password: $password) {
    token
    refreshToken
    errors { field message }
    user { id email }
  }
}

Create a checkout and add lines:

mutation CheckoutCreate($channel: String!, $lines: [CheckoutLineInput!]!) {
  checkoutCreate(input: { channel: $channel, lines: $lines }) {
    checkout {
      id
      token
      totalPrice { gross { amount currency } }
    }
    errors { field message }
  }
}

Complete checkout with a payment gateway token (e.g., from Stripe Elements):

mutation CheckoutComplete($checkoutId: ID!, $paymentData: JSONString) {
  checkoutComplete(id: $checkoutId, paymentData: $paymentData) {
    order { id number status }
    errors { field message code }
  }
}

Bootstrap a Saleor App

A Saleor App is a Node.js service that registers itself with Saleor, receives webhooks, and optionally renders UI in the dashboard via iframes.

npx @saleor/app-sdk@latest create my-saleor-app
cd my-saleor-app
npm install
npm run dev
# Expose with: npx ngrok http 3000

Register the app in the dashboard under Apps → Install custom app, entering your ngrok URL. Saleor calls your /api/manifest endpoint:

// pages/api/manifest.ts
import { createManifestHandler } from "@saleor/app-sdk/handlers/next";
import { AppManifest } from "@saleor/app-sdk/types";

const manifest: AppManifest = {
  id: "my-saleor-app",
  name: "My Saleor App",
  version: "1.0.0",
  about: "Example app",
  permissions: ["MANAGE_ORDERS"],
  appUrl: process.env.APP_URL!,
  tokenTargetUrl: `${process.env.APP_URL}/api/register`,
  webhooks: [
    {
      name: "Order Created",
      asyncEvents: ["ORDER_CREATED"],
      query: `subscription { event { ... on OrderCreated { order { id number } } } }`,
      targetUrl: `${process.env.APP_URL}/api/webhooks/order-created`,
      isActive: true,
    },
  ],
};

export default createManifestHandler({ manifestFactory: () => manifest });

Handle Saleor webhooks securely

Saleor signs every webhook with an HMAC-SHA256 signature using your app's secret token.

// pages/api/webhooks/order-created.ts
import { SaleorAsyncWebhook } from "@saleor/app-sdk/handlers/next";
import { OrderCreatedDocument } from "@/generated/graphql";

const orderCreatedWebhook = new SaleorAsyncWebhook<OrderCreatedPayload>({
  name: "Order Created",
  webhookPath: "api/webhooks/order-created",
  asyncEvent: "ORDER_CREATED",
  apl: saleorApp.apl,
  query: OrderCreatedDocument,
});

export default orderCreatedWebhook.createHandler((req, res, ctx) => {
  const { order } = ctx.payload;
  console.log(`New order #${order.number} received`);
  // Trigger fulfillment, email, ERP sync, etc.
  return res.status(200).end();
});

export const config = { api: { bodyParser: false } }; // required for signature check

Add a Dashboard Extension (custom UI panel)

Extensions render an iframe inside the Saleor Dashboard. Declare them in the manifest:

extensions: [
  {
    label: "Sync to ERP",
    mount: "PRODUCT_DETAILS_MORE_ACTIONS",
    target: "POPUP",
    permissions: ["MANAGE_PRODUCTS"],
    url: `${process.env.APP_URL}/extension/product-sync`,
  },
],

The extension page uses @saleor/app-sdk to communicate with the dashboard host:

import { actions, useAppBridge } from "@saleor/app-sdk/app-bridge";

export default function ProductSyncExtension() {
  const { appBridge } = useAppBridge();

  const handleSync = async () => {
    appBridge?.dispatch(actions.Notification({
      status: "success",
      title: "Sync started",
      text: "Product is being synced to ERP.",
    }));
  };

  return <button onClick={handleSync}>Sync to ERP</button>;
}

Examples

Paginated product catalog with TypeScript and graphql-request

import { GraphQLClient, gql } from 'graphql-request';

const client = new GraphQLClient(process.env.SALEOR_API_URL!, {
  headers: { Authorization: `Bearer ${process.env.SALEOR_APP_TOKEN}` },
});

const PRODUCTS_QUERY = gql`
  query Products($first: Int!, $after: String, $channel: String!) {
    products(first: $first, after: $after, channel: $channel) {
      edges { node { id name slug description } }
      pageInfo { hasNextPage endCursor }
    }
  }
`;

async function fetchAllProducts(channel: string) {
  const products = [];
  let after: string | null = null;

  do {
    const data = await client.request(PRODUCTS_QUERY, { first: 100, after, channel });
    products.push(...data.products.edges.map((e: any) => e.node));
    after = data.products.pageInfo.hasNextPage ? data.products.pageInfo.endCursor : null;
  } while (after);

  return products;
}

Order status update via Admin API

mutation FulfillOrder($orderId: ID!, $input: OrderFulfillInput!) {
  orderFulfill(orderId: $orderId, input: $input) {
    fulfillments {
      id
      status
      trackingNumber
    }
    errors { field message code }
  }
}

await client.request(FULFILL_ORDER_MUTATION, {
  orderId: "T3JkZXI6MTIz",
  input: {
    lines: [{ orderLineId: "T3JkZXJMaW5lOjQ1", stocks: [{ warehouse: "V2FyZWhvdXNlOjE=", quantity: 1 }] }],
    notifyCustomer: true,
    allowStockToBeExceeded: false,
  },
});

Best Practices

Use channels for multi-region or B2B/B2C separation — every product listing, pricing, and checkout is channel-scoped; create separate channels per locale/currency rather than duplicating products
Generate TypeScript types from the schema — run saleor app generate-types or use graphql-codegen so queries are fully typed
Store app tokens in Saleor's APL (Auth Persistence Layer) — the default file-based APL is fine for development; use Redis or Upstash APL in production
Always verify webhook signatures — use the SaleorAsyncWebhook wrapper which handles HMAC verification automatically; never process unauthenticated payloads
Use subscription-based webhook queries — Saleor webhooks use GraphQL subscriptions as the payload definition, giving you control over exactly which fields are included
Cache product catalog responses at the CDN layer — product data rarely changes; set Cache-Control: s-maxage=300 on catalog API routes
Use Saleor Cloud for production — self-hosting Django + Celery + Redis + PostgreSQL requires operational maturity; Saleor Cloud handles this

Common Pitfalls

Problem	Solution
GraphQL errors for unauthorized operations	Ensure the app has been granted the correct permissions in the manifest AND in the dashboard under App settings
Webhook payload is empty / fields missing	The webhook payload is defined by a GraphQL subscription query in the manifest — add the fields you need to the `query` property
`tokenCreate` returns null on storefront	The channel must have the storefront API enabled and an assigned country; check channel configuration in the dashboard
App works locally but not after deployment	The `APP_URL` env var must match the publicly accessible URL Saleor can reach; update the app URL in the dashboard after deployment
Dashboard extension iframe is blank	The extension URL must be served over HTTPS and must include `Access-Control-Allow-Origin` headers for the dashboard origin

Related Skills

@shopify-hydrogen
@composable-commerce
@webhook-architecture
@jamstack-storefront
@commerce-api-gateway

saleor-development