# Scopes

What each scope unlocks, how scope dependencies work, and why the merchant sees every scope before approving.

## How scopes work

- In your app version, declare **required** and **optional** scopes, each with a justification that the app review team sees.
- On install, the store owner sees every scope with its description. Required scopes can only be declined by declining the whole install; optional scopes are the merchant's choice.
- The token carries what the merchant actually approved in `scope`. Rely on that, not on what you requested.
- Some scopes depend on others. For example, `inventory:write` does not work without `inventory:read`. Request dependencies explicitly; LARM does not add them for you.

## Scopes that unlock the same endpoint

Some endpoints accept more than one scope, and any one of them is enough:

| Endpoint | Any of |
|---|---|
| Read categories | `categories:read` or `products:read` |
| Read a product price | `products.prices:read` or `products:read` |
| Any analytics report | `analytics:read` or the report's own scope, such as `analytics.sales:read` |

Request the narrowest scope that covers your use case; merchants approve narrow scopes faster, and app review is simpler.

## Customer data and digital content

Customer personal data and digital codes sit behind scopes separate from the order itself:

| You need | Scope |
|---|---|
| The order, its items, amounts and payment status | `orders:read` |
| Customer name, phone, email and shipping address | `customers:read` |
| Delivered digital codes and links | `orders.digital:read` |
| Abandoned carts | `carts:read`, plus `customers:read` for contact details |

Without `customers:read`, the `customer` and `shipping_address` keys are absent from the order, and these fields are not included in webhooks either. The app review team asks for the justification of each of these scopes, and rejects the request if it is broader than the app's function.

## Scope revocation

The merchant can revoke an optional scope at any time. You receive [`scopes.revoked`](/guides/app-uninstall), and scopes that depend on it are revoked with it. After that, the related endpoints return 403 `SCOPE_REQUIRED`, and the webhooks that need the scope stop. Call [`GET /me`](/api/me) to get the current scopes at any time.


## All scopes

## Analytics

### `analytics:read`

**Read sales reports.** Read all aggregated sales reports, without customer data.

- Read · Reviewed closely before approval

### `analytics.overview:read`

**Read sales overview.** Aggregated sales metrics. No customer data.

- Read · Reviewed closely before approval

### `analytics.sales:read`

**Read daily sales.** Sales totals by day. No customer data.

- Read · Reviewed closely before approval

### `analytics.products:read`

**Read product sales.** Aggregated sales per product. No customer data.

- Read · Reviewed closely before approval

### `analytics.categories:read`

**Read category sales.** Aggregated sales per category. No customer data.

- Read · Reviewed closely before approval

## Products

### `products:read`

**Read products and categories.** Read product content, prices, images and categories.

- Read

### `products:write`

**Create products and update content.** Create inactive products and update content; prices are a separate scope.

- Write · Requires `products:read`

### `products.prices:write`

**Update prices.** Update the price and previous price of a live product, effective immediately.

- Write · Requires `products:read` · Reviewed closely before approval

### `products.prices:read`

**Read product prices.** Read the price, previous price and pricing state only.

- Read

### `products.media:read`

**Read product media.** Read product images and alt text, without price or content.

- Read

### `products.media:write`

**Update product media.** Update the main image, additional images and alt text, after file checks.

- Write · Requires `products.media:read`

### `products.seo:read`

**Read product SEO.** Read the SEO title, description, keywords and social sharing image.

- Read

### `products.seo:write`

**Update product SEO.** Update the SEO title, description, keywords and social sharing image.

- Write · Requires `products.seo:read`

## Inventory

### `inventory:read`

**Read inventory availability.** Read physical quantities and digital product availability, without the codes.

- Read · Requires `products:read`

### `inventory:write`

**Adjust physical inventory.** Increase or decrease quantity with a reason; digital codes cannot be changed.

- Write · Requires `inventory:read` · Reviewed closely before approval

## Categories

### `categories:write`

**Manage categories.** Create categories and update their names, images and sort order.

- Write · Requires `products:read`

### `categories:read`

**Read categories.** Read category names, images and sort order, without product content.

- Read

## Pages

### `pages:read`

**Read store pages.** Read page content, drafts and SEO settings.

- Read

### `pages:write`

**Create and update pages.** Create drafts and update their content; updating a published page also requires the publish scope.

- Write · Requires `pages:read`

### `pages.publish:write`

**Publish and hide pages.** Change page visibility for visitors; separate from content updates.

- Write · Requires `pages:read` · Reviewed closely before approval

### `pages.delete:write`

**Delete pages.** Permanently delete a specific page; the update scope does not grant this.

- Write · Requires `pages:read` · Reviewed closely before approval

## Coupons

### `coupons:read`

**Read discount coupons.** Read discount rules and usage, without the customer email linked to the coupon.

- Read · Reviewed closely before approval

### `coupons.status:write`

**Activate and deactivate coupons.** Change the status of an existing coupon only; its value and conditions cannot be changed.

- Write · Requires `coupons:read` · Reviewed closely before approval

## Reviews

### `reviews:read`

**Read reviews.** Read review text, rating and publication state, without the customer's name, email or order number.

- Read

### `reviews.moderation:write`

**Publish and hide reviews.** Approve or hide a review; the customer's text cannot be changed and no messages are sent.

- Write · Requires `reviews:read` · Reviewed closely before approval

## Orders

### `orders:read`

**Read orders.** Read the full order: number, status, payment status, items, quantities, amounts, currency and the customer order link; without the customer's name and phone.

- Read · Reviewed closely before approval

### `orders.digital:read`

**Read delivered digital content.** The codes, links and files delivered to the customer in a paid order, so your app can deliver them to the customer.

- Read · Requires `orders:read` · Reviewed closely before approval

## Payments

### `payments:read`

**Read payments.** The outcome of each payment attempt (succeeded or failed) and its order ID only; no gateway, amount or card details.

- Read · Reviewed closely before approval

## Customers

### `customers:read`

**Read customer contact details.** Customer name, phone in international format, email and shipping address, inside orders, abandoned carts and their webhooks.

- Read · Reviewed closely before approval

## Abandoned carts

### `carts:read`

**Read abandoned carts.** Items, total and checkout link of unpaid carts.

- Read · Reviewed closely before approval