> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orderprotection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> Reference for all available OAuth scopes and permissions.

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.

<Tip>
  Only mark scopes as required if your app truly cannot function without them. Requesting fewer required scopes increases merchant trust and install rates.
</Tip>

## Available scopes

### Orders

| Scope | Description |
| - | - |
| `order:read` | Read order data including line items, totals, and fulfillment status |
| `order:update` | Update order data |

### Claims

| Scope | Description |
| - | - |
| `claim:read` | Read claim data and status |
| `claim:update` | Create and update claims |
| `claim:manage` | Full claim management including resolution |

### Customers

| Scope | Description |
| - | - |
| `customer:read` | Read customer data (name, email, address) |
| `customer:update` | Update customer records |

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

### Products

| Scope | Description |
| - | - |
| `product:read` | Read product catalog data |
| `product:update` | Create, update, and manage products |

### Store

| Scope | Description |
| - | - |
| `store:read` | Read store configuration and settings |
| `webhook:manage` | Create, read, update, and delete webhooks |
| `analytics:read` | Read store analytics and reporting data (see the [Analytics API](/developer/analytics-api)) |

### Settings

| Scope | Description |
| - | - |
| `partner-context:update` | Create, update, and delete partner contexts and their cohort resources — see [Partner contexts](/developer/endpoints#partner-contexts) |

<Note>
  **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.
</Note>

### Widgets

| Scope | Description |
| - | - |
| `widget:cart:read` | Read cart widget configuration (also covers `SUBSCRIPTION` widgets) |
| `widget:cart:update` | Update cart widget settings |
| `widget:checkout:read` | Read checkout widget configuration |
| `widget:checkout:update` | Update checkout widget settings |
| `widget:info-modal:read` | Read info modal widget configuration |
| `widget:info-modal:update` | Update info modal widget settings |

### A/B Testing

| Scope | Description |
| - | - |
| `ab-tests:read` | Read A/B test configurations and results |
| `ab-tests:update` | Create and manage A/B tests |

### Quotes

| Scope | Description |
| - | - |
| `quote:read` | Read price rule sets and calculate quotes |

### Policies

| Scope | Description |
| - | - |
| `policy:read` | Read individual policy details |
| `policy:list` | List policies for orders |

### Price Settings (Admin-Gated)

<Note>
  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.
</Note>

| Scope | Description |
| - | - |
| `store-credit:read` | Read store credit configuration |
| `store-credit:update` | Update store credit settings |
| `pricing:shipping-insurance:read` | Read shipping insurance pricing rules |
| `pricing:shipping-insurance:update` | Update shipping insurance pricing |
| `pricing:extended-warranty:read` | Read extended warranty pricing rules |
| `pricing:extended-warranty:update` | Update extended warranty pricing |
| `warranties:read` | Read warranty settings and pricing rules |
| `warranties:update` | Update warranty settings |

### Extensions (Admin-Gated)

| Scope | Description |
| - | - |
| `extension:deploy` | Deploy app extensions to the store |

## 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:

```json theme={null}
{
  "access_token": "op_at_...",
  "scope": "order:read claim:read store:read"
}
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.