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.
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
| Scope | Description |
|---|
read_orders | Read order data including line items, totals, and fulfillment status |
write_orders | Create and update orders |
Claims
| Scope | Description |
|---|
read_claims | Read claim data and status |
write_claims | Create and update claims |
manage_claims | Full claim management including resolution |
Customers
| Scope | Description |
|---|
read_customers | Read customer data (name, email, address) |
write_customers | Update customer records |
Customer scopes grant access to personally identifiable information (PII). Only request these if your app requires customer data.
Products
| Scope | Description |
|---|
read_products | Read product catalog data |
write_products | Create, update, and manage products |
Store
| Scope | Description |
|---|
read_store | Read store configuration and settings |
manage_webhooks | Create, read, update, and delete webhooks |
read_analytics | Read store analytics and reporting data |
| Scope | Description |
|---|
read_widget_cart | Read cart widget configuration |
write_widget_cart | Update cart widget settings |
read_widget_checkout | Read checkout widget configuration |
write_widget_checkout | Update checkout widget settings |
A/B Testing
| Scope | Description |
|---|
read_ab_tests | Read A/B test configurations and results |
write_ab_tests | Create and manage A/B tests |
Quotes
| Scope | Description |
|---|
read_quotes | Read protection quote data |
Policies
| Scope | Description |
|---|
read_policies | Read individual policy details |
list_policies | List policies for orders |
Price Settings (Admin-Gated)
The scopes below require OrderProtection admin approval. They are available only to public apps that have been reviewed and approved. Private apps cannot use admin-gated scopes.
| Scope | Description |
|---|
read_store_credit_settings | Read store credit configuration |
write_store_credit_settings | Update store credit settings |
read_shipping_insurance_pricing | Read shipping insurance pricing rules |
write_shipping_insurance_pricing | Update shipping insurance pricing |
read_extended_warranty_pricing | Read extended warranty pricing rules |
write_extended_warranty_pricing | Update extended warranty pricing |
read_warranty_pricing | Read warranty pricing rules |
write_warranty_pricing | Update warranty pricing |
Checking granted scopes
When you exchange an authorization code for tokens, the response includes a scope field listing the scopes the merchant actually granted:
{
"access_token": "op_at_...",
"scope": "read_orders read_claims read_store"
}
