# Scope reference

Every permission, with its risk level.

> **What is callable today:** all `*:read` scopes in the endpoint list, plus the write scopes `products:write`, `files:write`, `orders:write` and `subscriptions:write` (subscription links). Only scopes explicitly marked *(not callable in v1)* below are unavailable. The Store scopes `store:read`, `products:read`, `products:write`, `files:write`, `orders:read` and `orders:write` are callable in v1 through the routes listed in [Endpoints](/docs/dev/app-api/endpoints). The callable surface is always the list in [Endpoints](/docs/dev/app-api/endpoints).

A **scope** is a single permission. Your app can only touch data a merchant explicitly granted. Scopes are shown on the consent screen with their risk level, so over-asking directly costs you installs — and reviewers compare your scope list against what your app actually does.

## Naming

`resource:action` — e.g. `payments:read` = "list and view payments".

| Action | Means |
| --- | --- |
| `read` | List and retrieve objects. Never changes anything. |
| `write` | Create and update objects of that resource. |

## Risk levels

| Risk | Meaning |
| --- | --- |
| **Low** | Read-only, no personal or money-moving data. Approved by default. |
| **Medium** | Personal data or configuration changes. Needs a clear reason in your listing. |
| **High** | Moves or reverses money. Written justification at review, extra security checks. |
| **Restricted** | Financial reporting data. Granted case by case and revocable. |

## Catalog

| Scope | What it lets your app do | Typical use case | Risk |
| --- | --- | --- | --- |
| `merchant:read` | Read the merchant profile: name, country, city, VAT number, status, plan | Show whose account you are connected to | Low |
| `payments:read` | List and view payments | Order sync, reporting, reconciliation | Low |
| `refunds:read` | View refunds | Returns dashboards | Low |
| `customers:read` | Read buyer records (personal data). **No `/customers` endpoint in App API v1** — buyer name and email are returned inline on payments, invoices and subscriptions | CRM sync | Medium |
| `customers:write` | Create and update buyers *(not callable in v1; no `/customers` route exists)* | Two-way CRM sync | Medium |
| `products:read` | Read the product catalog, option groups and variants | Storefront, catalog sync | Low |
| `products:write` | Create, update and archive store products, prices, option groups, values and variants | Catalog management, PIM, Shopify/ERP sync | Medium |
| `store:read` | Read the merchant's Southbill Store: name, slug, branding, status | Storefront apps | Low |
| `files:write` | Upload product images, documents and covers (max 5 MB) | Catalog sync with media | Medium |
| `orders:read` | Read store orders with customer, shipping and fulfillment state | Order sync, fulfillment | Medium |
| `orders:write` | Update fulfillment/tracking and attach delivery evidence | Shipping automation | Medium |
| `invoices:read` | Read invoices | Accounting export | Low |
| `invoices:write` | Create, send and void invoices *(not callable in v1 — invoices are read-only in the App API)* | Invoicing tools | Medium |
| `subscriptions:read` | Read subscriptions | Churn analytics, entitlements | Low |
| `subscriptions:write` | Create, update and archive subscription links | Subscription link automation | High |
| `disputes:read` | Read disputes and deadlines | Chargeback alerting | Medium |
| `disputes:write` | Submit or update evidence *(not callable in v1 — disputes are read-only in the App API)* | Chargeback automation | High |
| `payouts:read` | Read payouts, bank settlement data and `/balance` | Bank reconciliation | Restricted |
| `analytics:read` | Aggregated volume figures | Dashboards | Low |
| `webhooks:read` | Read the merchant's webhook configuration *(not callable in v1 — app webhooks are configured in your developer dashboard)* | Diagnostics | Low |
| `webhooks:write` | Manage webhook endpoints *(not callable in v1)* | Auto-setup during install | Medium |

## Rules that trip people up

1. **Least privilege.** Reviewers reject scope lists that don't match the described functionality.
2. **Read before write.** Ask for Store write scopes only if your app really creates or updates catalog/order data.
3. **Adding a scope requires a new app version and re-consent** from every merchant. Missing scopes only surface as `403 insufficient_scope` at runtime — check the granted scopes after install and degrade gracefully.
4. **Restricted scopes can be revoked** if we see misuse; your app must keep working without them.
5. A missing scope returns `403` with `error.type: "insufficient_scope"` — see [Error & status codes](/docs/dev/dev-reference/errors).