Skip to main content
Scopes define what data and actions your app can access on behalf of a merchant. When creating your app, you declare the scopes it needs. Merchants review and approve these permissions during installation. Scope names follow a <domain>:<resource?>:<verb> colon-separated format (e.g. order:read, pricing:shipping-insurance:update).

​
Required vs. optional scopes

When configuring your app’s scopes, you can mark each one as:
  • Required — The merchant must grant this permission to install your app. They cannot opt out.
  • Optional — The merchant can choose to deny this permission during installation. Your app should handle gracefully when an optional scope is not granted.
Only mark scopes as required if your app truly cannot function without them. Requesting fewer required scopes increases merchant trust and install rates.

​
Available scopes

​
Orders

​
Claims

​
Customers

Customer scopes grant access to personally identifiable information (PII). Only request these if your app requires customer data.

​
Products

​
Store

​
Settings

Writes to cohort price sets and cohort widget configs require partner-context:update plus the matching per-type pricing or widget write scope; reads require only the per-type read scope. Merchant default settings are read-only for partners (store:read) — there is no partner write scope for merchant defaults.

​
Widgets

​
A/B Testing

​
Quotes

​
Policies

​
Price Settings (Admin-Gated)

The scopes below require OrderProtection admin approval. Public apps requesting them go through marketplace review; private apps requesting them are routed through the same OrderProtection review queue before they can be published and installed.

​
Extensions (Admin-Gated)

​
Checking granted scopes

When you exchange an authorization code (or client credentials) for tokens, the response includes a scope field listing the scopes the merchant actually granted:
If the merchant opted out of an optional scope, it will not appear in this list. Always check the granted scopes before calling endpoints that require specific permissions.