# saleor-app

Patterns for building Saleor apps that handle the app protocol, webhooks, payment processing, settings storage and Dashboard integration.

Skill by Saleor. Category: Web and browsers.

## Install

Project (for this project only):

```sh
npx skills add saleor/agent-skills --skill saleor-app
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add saleor/agent-skills --skill saleor-app -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Warn

Installs: 420. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/saleor/agent-skills/saleor-app)

## Source

[Open the source](https://github.com/saleor/agent-skills/tree/HEAD/skills/saleor-app). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: saleor-app
description: >
  Universal Saleor app development patterns. Covers the app protocol (manifest, registration,
  webhooks, authentication), payment processing, SDK abstractions, settings persistence, and
  Dashboard integration. Framework-agnostic with Next.js examples.
license: MIT
metadata:
  author: saleor
  version: "1.0.0"
---

# Saleor App

Guide for building apps that extend Saleor via webhooks and the GraphQL API.
Framework-agnostic protocol documentation with Next.js examples using `@saleor/app-sdk`.

## When to Apply

- Defining an app manifest or registering webhooks
- Handling async/sync webhook events from Saleor
- Building payment apps with the Transaction API and provider webhooks
- Authenticating requests (registration handshake, JWT, signature verification)
- Storing app settings in Saleor metadata
- Building Dashboard UI inside the iframe
- Making GraphQL calls with app tokens
- Debugging webhook failures, auth errors, or permission issues
- Deciding who can view the app and what they should see (user vs app scope)

## Rule Categories by Priority

| Priority | Category        | Impact   | Prefix          |
| -------- | --------------- | -------- | --------------- |
| 1        | Protocol        | CRITICAL | `protocol-`     |
| 2        | Permissions     | CRITICAL | `permissions-`  |
| 3        | Payment Apps    | CRITICAL | `payment-`      |
| 4        | Webhooks        | HIGH     | `webhook-`      |
| 5        | Data & Settings | HIGH     | `data-`         |
| 6        | Dashboard UI    | MEDIUM   | `dashboard-`    |
| 7        | Development     | MEDIUM   | `dev-`          |

## Quick Reference

### 1. Protocol (CRITICAL)

- `protocol-manifest` — App manifest, required endpoints, permissions, extensions
- `protocol-auth` — Registration handshake, APL, token scopes, JWT/signature verification

### 2. Permissions (CRITICAL)

- `permissions-access-scopes` — Define per-feature permissions; guard user JWT on every API route; baseline + per-route meta; UI mirrors server

### 3. Payment Apps (CRITICAL)

- `payment-app` — Financial truth, stable references, unknown outcomes, refunds, and reconciliation

### 4. Webhooks (HIGH)

- `webhook-async` — Async event handling, payload typing, retry policy, signature verification
- `webhook-sync` — Sync event handling, response schemas, performance constraints
- `webhook-external` — Receiving webhooks from external services, multi-tenant routing

### 5. Data & Settings (HIGH)

- `data-graphql` — GraphQL from apps: client setup, auth headers, codegen, app vs user tokens
- `data-settings` — MetadataManager, EncryptedMetadataManager, domain-scoped persistence

### 6. Dashboard UI (MEDIUM)

- `dashboard-appbridge` — AppBridge iframe protocol, actions, events, theme/locale sync

### 7. Development (MEDIUM)

- `dev-debug` — Common errors, webhook dry runs, tunnel setup, debugging checklist
````

- Previous: [transformation-builder](https://syn4pse.dev/terminal/imagekit-transformation-builder.md)
- Next: [imagekit-integrations](https://syn4pse.dev/terminal/imagekit-integrations.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
