Scopes & permissions
Scopes follow the pattern resource:action, for example orders:read. The same scopes apply to API keys, OAuth tokens and MCP.
How scopes work#
- Request only what you need. Merchants see the list on the consent screen and in the backend.
- Read and write are separate. Orders have extra scopes for fulfillment, notes, cancellation, refunds and edits.
- Missing scopes return
403 forbidden with the scope name. On PATCH /orders/{id} every field group is checked before anything is written. - The REST API uses the read scopes plus
orders:fulfillment, orders:notes, orders:cancel and inventory:write. The other write scopes are used by MCP tools.
Scopes with live effect#
⚡These 16 scopes change the live shop or move money immediately — there is no draft step. Ask the merchant before automating them.
orders:cancel orders:refund products:write collections:write discounts:write reviews:write inbox:write inventory:write markets:write settings:write tracking:write domains:write email:write shop:write shop:publish popups:write
All scopes#
orders#
| Scope | Type | Description | Used by |
|---|
orders:read | read | Read orders, including financial fields and attribution | REST · MCP |
orders:fulfillment | write | Change fulfillment status and tracking | REST · MCP |
orders:cancel live | write | Cancel orders | REST · MCP |
orders:refund live | write | Refund orders (money is returned immediately) | MCP |
orders:edit | write | Edit orders | MCP |
orders:notes | write | Write internal order notes | REST · MCP |
products#
| Scope | Type | Description | Used by |
|---|
products:read | read | Read products and offers | REST · MCP |
products:write live | write | Create and change products and offers (live) | MCP |
customers#
| Scope | Type | Description | Used by |
|---|
customers:read | read | Read customers | REST · MCP |
customers:write | write | Change customers | — |
collections#
| Scope | Type | Description | Used by |
|---|
collections:read | read | Read collections | REST · MCP |
collections:write live | write | Create and change collections (live) | MCP |
discounts#
| Scope | Type | Description | Used by |
|---|
discounts:read | read | Read discount codes | REST · MCP |
discounts:write live | write | Create and change discount codes (live) | MCP |
reviews#
| Scope | Type | Description | Used by |
|---|
reviews:read | read | Read reviews | REST · MCP |
reviews:write live | write | Approve and answer reviews (live) | MCP |
inbox#
| Scope | Type | Description | Used by |
|---|
inbox:read | read | Read the inbox | MCP |
inbox:write live | write | Send inbox messages to customers (sent immediately) | MCP |
inventory#
| Scope | Type | Description | Used by |
|---|
inventory:read | read | Read stock levels | REST · MCP |
inventory:write live | write | Change stock levels | REST · MCP |
revenue#
| Scope | Type | Description | Used by |
|---|
revenue:read | read | Read revenue and reports | REST · MCP |
markets#
| Scope | Type | Description | Used by |
|---|
markets:read | read | Read markets and taxes | MCP |
markets:write live | write | Change markets and taxes (live) | MCP |
settings#
| Scope | Type | Description | Used by |
|---|
settings:read | read | Read shop settings and legal texts | MCP |
settings:write live | write | Change shop settings and legal texts (live) | MCP |
tracking#
| Scope | Type | Description | Used by |
|---|
tracking:read | read | Read tracking and cookie settings | MCP |
tracking:write live | write | Change tracking and cookie settings (live) | MCP |
domains#
| Scope | Type | Description | Used by |
|---|
domains:read | read | Read domains | MCP |
domains:write live | write | Connect and change domains (live) | MCP |
email#
| Scope | Type | Description | Used by |
|---|
email:read | read | Read sender addresses and order e-mails | MCP |
email:write live | write | Change sender addresses and order e-mails (live) | MCP |
reports#
| Scope | Type | Description | Used by |
|---|
reports:read | read | Read analytics reports | MCP |
shop#
| Scope | Type | Description | Used by |
|---|
shop:read | read | Read the shop structure (pages, sections, theme) | MCP |
pages:write | write | Create pages (draft) | MCP |
sections:write | write | Edit sections (draft) | MCP |
theme:write | write | Change fonts and colors (draft) | MCP |
shop:write live | write | Set up shipping (live at checkout) | MCP |
shop:publish live | write | Publish the shop and set its password (live) | MCP |
| Scope | Type | Description | Used by |
|---|
popups:read | read | Read pop-ups | MCP |
popups:write live | write | Create and activate pop-ups (live when activated) | MCP |
marketing#
| Scope | Type | Description | Used by |
|---|
marketing:read | read | Read e-mail designs and flows | MCP |
marketing:write | write | Edit e-mail designs and flows (draft) | MCP |
marketing:send | write | Send test e-mails and activate flows | MCP |
ecomone