OAuth Scopes

Scopes define the permissions your app requests from the merchant at the moment of consent. Always request the minimum scopes your integration actually needs.

Scope table

Scope	Access granted
`read:products`	List and read products, variants, images, and metadata
`write:products`	Create, update, and delete products and variants
`read:categories`	List and read product categories
`write:categories`	Create, update, and delete categories
`read:inventory`	Read inventory levels by variant and location
`write:inventory`	Update inventory quantities
`read:discounts`	List and read discounts, coupons, and promotions
`write:discounts`	Create, update, and delete discounts
`read:orders`	List and read orders, line items, and shipments
`write:orders`	Update order status, add notes, process returns
`read:customers`	List and read customers, addresses, and order history
`write:customers`	Create and update customers and addresses
`read:store`	Read general store information (name, currency, language, etc.)
`write:store`	Update general store settings
`read:analytics`	Access sales, visit, and conversion metrics
`read:webhooks`	List webhooks configured on the store
`write:webhooks`	Create, update, and delete webhooks

How scopes are shown to the user

On the consent screen, scopes are grouped into merchant-friendly categories that describe the store area affected:

Your catalog — read:products, write:products, read:categories, write:categories, read:inventory, write:inventory, read:discounts, write:discounts
Your sales — read:orders, write:orders
Your customers — read:customers, write:customers
Your store settings — read:store, write:store
Your reports — read:analytics
Automation — read:webhooks, write:webhooks

Best practices

Minimum privilege — only request scopes your integration actively uses. Extra scopes create distrust with the user.
Read vs. write scopes — if your app only reads data, do not request write:* scopes.
Expanding scopes — if you later need additional scopes, start a new authorization flow. The user must consent again.
Scopes in registration — declare in the scope field of client registration the maximum set of scopes your app may request.

Scopes in the access token

The scope field in the token endpoint and introspection responses reflects exactly which scopes were granted by the user — which may be a subset of what you requested if the user denied some.

{
  "active": true,
  "scope": "read:products read:orders",
  ...
}

Always validate that the token includes the required scope before attempting the operation.

Scope table

How scopes are shown to the user

Best practices

Scopes in the access token

On this page