---
name: saleor-apps-6c8f7b715a33
description: >
  Develop Saleor Apps — App manifest, saleor-app-sdk, Next.js template,
  permissions, token exchange, APL, App Bridge, and lifecycle management. Use
  when building Saleor App extensions.
---

# Saleor App Development

## Before writing code

**Fetch live docs**:
1. Fetch `https://docs.saleor.io/developer/extending/apps/overview` for Apps architecture
2. Web-search `site:docs.saleor.io saleor app manifest structure` for manifest reference
3. Web-search `site:docs.saleor.io saleor-app-sdk token exchange APL` for SDK utilities
4. Web-search `site:github.com saleor/saleor-app-template` for latest Next.js App template
5. Web-search `site:docs.saleor.io app permissions` for permission enumeration
6. Web-search `site:docs.saleor.io app bridge dashboard extensions` for Bridge API

## App Architecture

Saleor 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 |

### Legacy Plugins Deprecation

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.

## App Manifest

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.

## saleor-app-sdk

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.

## Auth Persistence Layer (APL)

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.

## App Installation Flow

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

## App Permissions

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

## App Template (Next.js)

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.

## Local Development

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

## Authenticated GraphQL Client

After installation, use the stored auth token to call the Saleor API:

```typescript
// 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 })
}
```

## Best Practices

- Build all new extensions as Apps, not legacy plugins
- Store auth tokens securely using an appropriate APL for your deployment target
- Request only the permissions your App needs -- follow least privilege
- Use subscription queries in webhook definitions for precise payload control
- Verify webhook signatures (JWS default since 3.5+, HMAC deprecated) before processing any payload
- Use `saleor app tunnel` during development for reliable webhook delivery
- Handle the `SALEOR_API_URL_HEADER` to support multi-tenant App installations
- Test the full install/uninstall lifecycle before deploying to production

Fetch the Saleor Apps documentation for exact manifest fields, SDK method signatures, and APL configuration patterns before implementing.


---
Source attribution: OrcaQubits
Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/saleor-commerce/skills/saleor-apps/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2024-2026 OrcaQubits AI (https://orcaqubits-ai.com)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: OrcaQubits
Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/saleor-commerce/skills/saleor-apps/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Product Management
Roles: Backend Developer, DevOps / SRE, Growth Product Manager, Product Manager, Technical Product Manager
Specialties: API, Backend
Tools: Saleor, Next.Js
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: ca42f02a069ea72d3babf62a35a82bee79b6bcd732272d3daf5b1831b75419cf