finsilabs/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

| 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