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

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

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

### Products

| Scope            | Description                         |
| ---------------- | ----------------------------------- |
| `read_products`  | Read product catalog data           |
| `write_products` | Create, update, and manage products |

### Store

| Scope             | Description                               |
| ----------------- | ----------------------------------------- |
| `manage_webhooks` | Create, read, update, and delete webhooks |
| `read_analytics`  | Read store analytics and reporting data   |

### Settings

| Scope            | Description                                                                   |
| ---------------- | ----------------------------------------------------------------------------- |
| `read_store`     | Read store configuration and settings                                         |
| `write_settings` | Create, update, and delete partner contexts; update merchant default settings |

### Widgets

| 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      |
| `read_widget_info_modal`  | Read info modal widget configuration |
| `write_widget_info_modal` | Update info modal 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)

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

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

```json theme={null}
{
  "access_token": "op_at_...",
  "scope": "read_orders read_claims read_store"
}
```

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.