# Scope reference

Every permission, with its risk level.

> **App API v1 is read-only.** Only `*:read` scopes are callable today; every write scope below is reserved for future versions and granted case by case after review. Requesting one does not enable a write endpoint.

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. |
| `create` / `capture` / `cancel` | Narrow, money-moving actions that are granted separately. |

## 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, currency | Show whose account you are connected to | Low |
| `payments:read` | List and view payments | Order sync, reporting, reconciliation | Low |
| `payments:create` | Start new payments | Custom checkout, POS terminal | High |
| `payments:capture` | Capture a previously authorized payment | Ship-then-charge flows | High |
| `payments:cancel` | Release an uncaptured authorization | Cancelled orders | High |
| `refunds:read` | View refunds | Returns dashboards | Low |
| `refunds:create` | Issue refunds — moves money out | Returns automation | High |
| `customers:read` | Read buyer records (personal data) | CRM sync | Medium |
| `customers:write` | Create and update buyers | Two-way CRM sync | Medium |
| `products:read` | Read catalog and prices | Storefront, catalog sync | Low |
| `products:write` | Create and update products/prices | Catalog management, PIM | Medium |
| `invoices:read` | Read invoices | Accounting export | Low |
| `invoices:write` | Create, send and void invoices | Invoicing tools | Medium |
| `subscriptions:read` | Read subscriptions | Churn analytics, entitlements | Low |
| `subscriptions:write` | Change plans, quantities, cancel | Subscription management | High |
| `disputes:read` | Read disputes and deadlines | Chargeback alerting | Medium |
| `disputes:write` | Submit or update evidence | Chargeback automation | High |
| `payouts:read` | Read payouts and bank settlement data | Bank reconciliation | Restricted |
| `analytics:read` | Aggregated volume figures | Dashboards | Low |
| `webhooks:read` | Read the merchant's webhook configuration | Diagnostics | Low |
| `webhooks:write` | Manage webhook endpoints | 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.** Ship the read-only version, add write scopes in a later version with a proven track record.
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).