Scope reference

Every permission, with its risk level.

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.