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. The callable surface is always the list in 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.