From saleor-commerce
Develops Saleor Apps using app manifest, saleor-app-sdk, Next.js templates, permissions, token exchange, APL, App Bridge, and lifecycle management. Use for building Saleor extensions.
npx claudepluginhub orcaqubits/agentic-commerce-skills-plugins --plugin saleor-commerceThis skill is limited to using the following tools:
**Fetch live docs**:
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Guides MCP server integration in Claude Code plugins via .mcp.json or plugin.json configs for stdio, SSE, HTTP types, enabling external services as tools.
Fetch live docs:
https://docs.saleor.io/docs/developer/extending/apps/overview for Apps architecturesite:docs.saleor.io saleor app manifest structure for manifest referencesite:docs.saleor.io saleor-app-sdk token exchange APL for SDK utilitiessite:github.com saleor/saleor-app-template for latest Next.js App templatesite:docs.saleor.io app permissions for permission enumerationsite:docs.saleor.io app bridge dashboard extensions for Bridge APISaleor Apps are standalone web applications that extend Saleor functionality. They are not monolithic plugins embedded in the core -- each App is an independent service that communicates with Saleor via GraphQL and webhooks.
| Aspect | Detail |
|---|---|
| Deployment | Standalone web app (any host) |
| Communication | GraphQL API + webhooks |
| Framework | Any (official template uses Next.js) |
| Registration | Installed via manifest URL |
| Authentication | App token issued during installation |
| Dashboard UI | Rendered in an iframe via App Bridge |
Saleor's legacy plugin system (Python classes in saleor/plugins/) is deprecated. All new extensions should be built as Apps. Legacy plugins will be removed in a future major version.
The manifest is a JSON document served at a public URL that describes the App:
| Field | Type | Purpose |
|---|---|---|
id | string | Unique identifier for the App |
version | string | Semantic version |
name | string | Display name |
about | string | Short description |
permissions | string[] | Required Saleor permissions |
appUrl | string | Main App URL (loaded in Dashboard iframe) |
configurationUrl | string | App settings page URL |
tokenTargetUrl | string | URL that receives the auth token during install |
dataPrivacyUrl | string | Privacy policy URL |
homepageUrl | string | App homepage URL |
supportUrl | string | Support contact URL |
webhooks | object[] | Webhook subscriptions |
extensions | object[] | Dashboard mounting points |
The manifest URL is provided when installing the App via the Dashboard or the appInstall mutation.
The official TypeScript SDK provides core utilities for building Saleor Apps:
| Utility | Purpose |
|---|---|
SaleorApp | Main App class coordinating APL, manifest, handlers |
createManifestHandler | Next.js API route handler for manifest endpoint |
createAppRegisterHandler | Handler for the token exchange callback |
withRegisteredSaleorDomainHeader | Middleware to verify request origin |
verifyJWT | Verify Saleor-issued JWTs in webhook requests |
getAppId | Retrieve the App's ID from the token |
SALEOR_API_URL_HEADER | Standard header name for Saleor instance URL |
SALEOR_AUTHORIZATION_BEARER_HEADER | Standard header for App auth token |
Install via npm install @saleor/app-sdk -- fetch live docs for the current version.
The APL stores the mapping between Saleor instance URLs and the App's auth tokens:
| APL Type | Storage | Use Case |
|---|---|---|
FileAPL | Local JSON file | Development only |
UpstashAPL | Upstash Redis | Serverless production |
SaleorCloudAPL | Saleor Cloud | Apps deployed to Saleor Cloud |
EnvAPL | Environment variable | Single-tenant simple deployments |
| Custom | Any store | Implement the APL interface |
The APL is critical -- without it, the App cannot authenticate requests from Saleor after a server restart.
| Step | Actor | Action |
|---|---|---|
| 1 | Admin | Provides manifest URL in Dashboard |
| 2 | Saleor | Fetches manifest, validates permissions |
| 3 | Saleor | Sends auth token to tokenTargetUrl |
| 4 | App | Stores token in APL |
| 5 | Saleor | Marks App as installed |
| 6 | App | Uses stored token for all future API calls |
| Permission | Scope |
|---|---|
MANAGE_PRODUCTS | Create, update, delete products |
MANAGE_ORDERS | View and manage orders |
MANAGE_CHECKOUTS | Manage checkout sessions |
MANAGE_USERS | View and manage customers |
MANAGE_SHIPPING | Configure shipping methods |
MANAGE_DISCOUNTS | Create and manage promotions |
MANAGE_CHANNELS | Configure channels |
MANAGE_APPS | Install and manage other Apps |
HANDLE_PAYMENTS | Process payment transactions |
HANDLE_TAXES | Calculate taxes for checkout |
Request only the permissions your App actually needs -- the principle of least privilege.
The official saleor-app-template scaffolds a Next.js App with all SDK wiring:
| File | Purpose |
|---|---|
pages/api/manifest.ts | Serves the App manifest |
pages/api/register.ts | Handles token exchange |
pages/api/webhooks/*.ts | Webhook handler endpoints |
pages/index.tsx | Main App page (Dashboard iframe) |
saleor-app.ts | SaleorApp instance and APL configuration |
lib/saleor-client.ts | Authenticated GraphQL client factory |
Scaffold with npx @saleor/cli app create -- fetch live docs for current template version.
| Task | Command / Tool |
|---|---|
| Start dev server | npm run dev (Next.js on port 3000) |
| Expose locally | saleor app tunnel or ngrok |
| Install in Saleor | Provide tunnel URL as manifest URL |
| View logs | Check terminal output and Saleor Dashboard App logs |
| Test webhooks | Use tunnel + Saleor triggers |
The tunnel is required because Saleor must reach your App over HTTPS to deliver webhooks and fetch the manifest.
After installation, use the stored auth token to call the Saleor API:
// lib/saleor-client.ts
// Fetch live docs for current client setup pattern
import { createGraphQLClient } from "@saleor/apps-shared"
export function createClient(saleorApiUrl: string, token: string) {
return createGraphQLClient({ saleorApiUrl, token })
}
saleor app tunnel during development for reliable webhook deliverySALEOR_API_URL_HEADER to support multi-tenant App installationsFetch the Saleor Apps documentation for exact manifest fields, SDK method signatures, and APL configuration patterns before implementing.