Scopes

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

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:

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