Saleor Development

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

1. 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

2. 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();

3. 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 }
     }
   }

4. 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 });

5. 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

6. 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

Related Skills

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

Saleor Dashboard Extension: Inventory Reservation Button

Problem/Feature Description

A wholesale distributor manages their product catalog in Saleor and also maintains an external warehouse management system (WMS). Their operations team spends time manually copying SKUs and stock levels between the two systems. To reduce this friction, the engineering team wants to embed a "Reserve Inventory" button directly inside the Saleor product details page. When a staff member clicks the button, it should trigger a reservation request to the WMS and show a success or failure notification within the Saleor Dashboard — without navigating away.

The team has already built a Saleor App skeleton (manifest and registration endpoint exist). They now need to extend the manifest to declare the Dashboard Extension and build the React page that renders inside the dashboard iframe. The extension should be accessible from the product details page and communicate with the dashboard shell to display status notifications. A README or inline comments should describe the HTTPS and CORS requirements for the extension page to work in production.

Output Specification

Produce the following files:

• pages/api/manifest.ts — updated manifest handler that declares the Dashboard Extension
• pages/extension/inventory-reserve.tsx — the React page rendered inside the extension iframe
• README.md — brief notes on deployment requirements for the extension to work correctly in production (HTTPS, CORS)

The extension page should simulate the WMS call (a placeholder async function is fine) and show a notification in the dashboard on completion. Do not implement real WMS API calls — a mock/stub is sufficient.

Order Event Processor for Saleor

Problem/Feature Description

A logistics startup has recently integrated Saleor as their e-commerce backend and needs to build a lightweight service that reacts in real-time when orders are placed. Whenever a customer completes checkout, the service should receive the order data from Saleor and hand it off to their internal fulfillment pipeline. The engineering team has decided to build a dedicated Saleor App — a Node.js service that lives outside of Saleor itself and communicates with it via the app registration protocol and webhook events.

The team is starting from scratch and wants a minimal but correct implementation. They need the app manifest, the registration endpoint, and a working webhook handler that fires when an order is placed. Security is a priority: the service must authenticate incoming webhook payloads rather than blindly trusting them. The handler should log enough order details to hand off to the fulfillment pipeline.

Output Specification

Write the TypeScript source files for a Next.js-based Saleor App. Produce the following files in your working directory:

• package.json — dependencies needed to run the app
• pages/api/manifest.ts — the app manifest handler
• pages/api/register.ts — the token registration endpoint
• pages/api/webhooks/order-created.ts — the order creation webhook handler

For each file include brief inline comments explaining key decisions.

Product Catalog API for a Next.js Storefront

Problem/Feature Description

A fashion retailer is building a new Next.js storefront on top of their Saleor backend. Their marketing team regularly runs promotions for different regions — Europe uses EUR pricing while the US uses USD — so the backend is configured with multiple channels to handle regional pricing and availability. The storefront team needs a reliable way to fetch the full product catalog, including names, slugs, thumbnails, and pricing, so it can power both the homepage grid and a search index.

The catalog contains thousands of products, so a single query won't return everything. The team needs a TypeScript utility that can walk through all pages of results and return the complete list. Performance matters: catalog data barely changes during the day, so the team wants CDN-level caching on the API route that serves this data. They also need the code to be type-safe since the frontend is entirely TypeScript.

Output Specification

Write a TypeScript implementation with the following files:

• lib/saleorClient.ts — GraphQL client setup targeting the Saleor API
• lib/fetchAllProducts.ts — a function that fetches all products from a given channel, handling large catalogs across multiple pages, returning a typed array
• pages/api/catalog.ts — a Next.js API route that calls fetchAllProducts and returns JSON, with appropriate caching headers set on the response

Include a graphql-codegen.yml (or equivalent config) or inline type definitions that show how types are generated from the Saleor schema.

You may use environment variables such as NEXT_PUBLIC_SALEOR_API_URL and SALEOR_APP_TOKEN — do not hardcode URLs or tokens.