Scopes
How scopes work
A scope has the form <action>:<resource>, for example read:products orwrite:orders. You choose the scopes when you create a secret key.
Four wildcards cover many resources at once:
*:*gives full access to every resource.read:*gives read access to every resource.write:*gives write access to every resource.admin:*gives admin access, the owner-level operations.
A key marked read only is refused on any operation that is not a read, whatever scopes it holds. A request needs every scope its operation lists. The exception is an operation marked "any of" below, where holding one of the listed scopes is enough.
This page is generated from the Store API reference. Each table lists the operations that need the scope, and the "Also needs" column shows the other scopes the same operation lists. The reference version is shown at the bottom.
admin:store
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/hosting/env | List environment variables | |
PUT | /stores/{storeRef}/hosting/env/{name} | Set an environment variable | |
DELETE | /stores/{storeRef}/hosting/env/{name} | Delete an environment variable | |
POST | /stores/{storeRef}/hosting/forwarder-secret/rotate | Rotate the forwarder secret | |
DELETE | /stores/{storeRef}/integrations/github | Disconnect GitHub | |
GET | /stores/{storeRef}/storefront/repo | Get storefront code status | |
POST | /stores/{storeRef}/storefront/repo | Create the storefront repository | |
GET | /stores/{storeRef}/storefront/template | Get the latest storefront template release | |
GET | /stores/{storeRef}/storefront/template/download | Download the storefront template |
deploy:storefront
read:analytics
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/analytics/summary | Get the analytics summary | |
GET | /stores/{storeRef}/analytics/time-series | Get the revenue time series | |
GET | /stores/{storeRef}/reports | List saved reports | |
POST | /stores/{storeRef}/reports/pins | Pin a report | |
DELETE | /stores/{storeRef}/reports/pins | Unpin a report | |
GET | /stores/{storeRef}/reports/presets | List report presets | |
POST | /stores/{storeRef}/reports/run | Run a report | |
GET | /stores/{storeRef}/reports/schema | Get the report schema | |
POST | /stores/{storeRef}/reports/views | Record a report view |
read:assets
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/assets | List assets | |
GET | /stores/{storeRef}/assets/{assetId} | Get an asset | |
GET | /stores/{storeRef}/assets/entity/{entity_type}/{entity_id} | List the assets of a record |
read:blog
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/blog/categories | List blog categories | |
GET | /stores/{storeRef}/blog/categories/all | List all blog categories | |
GET | /stores/{storeRef}/blog/comments | List blog comments | |
GET | /stores/{storeRef}/blog/posts | List blog posts | |
GET | /stores/{storeRef}/blog/posts/{id} | Get a blog post | |
GET | /stores/{storeRef}/blog/posts/{id}/metafields | Get blog post metafields | |
GET | /stores/{storeRef}/blog/posts/{postId}/comments | List comments on a blog post | |
GET | /stores/{storeRef}/blog/posts/all | List all published blog posts | |
GET | /stores/{storeRef}/blog/posts/stats/overview | Get blog statistics | |
GET | /stores/{storeRef}/blog/settings | Get blog settings | |
GET | /stores/{storeRef}/blog/tags | List blog tags | |
GET | /stores/{storeRef}/blog/tags/all | List all blog tags |
read:categories
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/collections | List collections | |
GET | /stores/{storeRef}/collections/{id} | Get a collection | |
GET | /stores/{storeRef}/collections/{id}/metafields | Get collection metafields | |
GET | /stores/{storeRef}/collections/all | List all collections without pagination |
read:customers
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/customers | List customers | |
GET | /stores/{storeRef}/customers/{customerId} | Get a customer | |
GET | /stores/{storeRef}/customers/{customerId}/insights | Get a customer's purchase insights | |
GET | /stores/{storeRef}/customers/{customerId}/orders | List a customer's orders | |
GET | /stores/{storeRef}/customers/{customerId}/reviews | List a customer's reviews | |
GET | /stores/{storeRef}/customers/{customerId}/timeline | Get a customer's timeline | |
GET | /stores/{storeRef}/customers/{email} | Get a customer by email | |
GET | /stores/{storeRef}/customers/{email}/addresses | List a customer's addresses by email | |
GET | /stores/{storeRef}/customers/{id}/metafields | Get customer metafields | |
GET | /stores/{storeRef}/customers/statistics | Get customer statistics |
read:inventory
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/inventory/export | Export stock levels as CSV | |
GET | /stores/{storeRef}/inventory/levels | List stock levels | |
GET | /stores/{storeRef}/inventory/locations | List inventory locations | |
GET | /stores/{storeRef}/inventory/locations/{id}/metafields | Get inventory location metafields | |
GET | /stores/{storeRef}/inventory/variants/{variantId}/history | Get a variant's stock history |
read:menus
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/menus | List menus | |
GET | /stores/{storeRef}/menus/{id} | Get a menu | |
GET | /stores/{storeRef}/menus/ref/{ref} | Get a menu by reference |
read:metafields
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/metafield-definitions | List metafield definitions | |
GET | /stores/{storeRef}/metafield-definitions/{id} | Get a metafield definition | |
GET | /stores/{storeRef}/metafield-definitions/counts | Count metafield definitions per owner type |
read:metaobjects
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/metaobject-definitions | List metaobject definitions | |
GET | /stores/{storeRef}/metaobject-definitions/{id} | Get a metaobject definition | |
GET | /stores/{storeRef}/metaobjects/{type}/entries | List metaobject entries | |
GET | /stores/{storeRef}/metaobjects/{type}/entries/{id} | Get a metaobject entry |
read:orders
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/orders | List orders | |
GET | /stores/{storeRef}/orders/{id} | Get an order | |
GET | /stores/{storeRef}/orders/{id}/allowed-transitions | Get allowed status transitions | |
GET | /stores/{storeRef}/orders/{id}/metafields | Get order metafields | |
GET | /stores/{storeRef}/orders/{id}/shipments | List an order's shipments | |
GET | /stores/{storeRef}/orders/{id}/timeline | Get the order timeline | |
GET | /stores/{storeRef}/orders/statistics | Get order statistics |
read:pages
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/content-pages | List content pages | |
GET | /stores/{storeRef}/content-pages/{id} | Get a content page | |
GET | /stores/{storeRef}/content-pages/{id}/metafields | Get content page metafields | |
GET | /stores/{storeRef}/content-pages/all | List all content pages | |
GET | /stores/{storeRef}/content-pages/statistics | Get content page statistics |
read:products
read:promotions
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/promotions | List promotions | |
GET | /stores/{storeRef}/promotions/{id} | Get a promotion | |
GET | /stores/{storeRef}/promotions/code/{code} | Get a promotion by code | |
GET | /stores/{storeRef}/promotions/stats/overview | Get promotion statistics | |
POST | /stores/{storeRef}/promotions/validate | Validate a promotion code |
read:purchase_orders
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/purchase-orders | List purchase orders | |
GET | /stores/{storeRef}/purchase-orders/{id} | Get a purchase order | |
GET | /stores/{storeRef}/purchase-orders/{id}/pdf | Download a purchase order as a PDF | |
GET | /stores/{storeRef}/suppliers | List suppliers | |
GET | /stores/{storeRef}/suppliers/{id} | Get a supplier |
read:reviews
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/reviews | List reviews | |
GET | /stores/{storeRef}/reviews/{reviewId} | Get a review | |
GET | /stores/{storeRef}/reviews/stats | Get review statistics |
read:settings
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/email-templates | List email templates | |
GET | /stores/{storeRef}/email-templates/{name} | Get an email template | |
POST | /stores/{storeRef}/email-templates/{name}/preview | Preview an email template | |
POST | /stores/{storeRef}/email-templates/branding-preview | Preview email branding | |
GET | /stores/{storeRef}/metafields | Get shop metafields | |
GET | /stores/{storeRef}/settings | Get store settings | |
GET | /stores/{storeRef}/settings/auth | Get customer sign-in settings | |
GET | /stores/{storeRef}/themes | List themes | |
GET | /stores/{storeRef}/themes/{id} | Get a theme | or deploy:storefront |
POST | /stores/{storeRef}/themes/{id}/preview-token | Create a theme preview token | |
GET | /stores/{storeRef}/themes/{id}/versions | List theme versions | or deploy:storefront |
read:shippings
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores/{storeRef}/shipping-zones | List shipping zones | |
GET | /stores/{storeRef}/shipping-zones/{id} | Get a shipping zone | |
GET | /stores/{storeRef}/shipping-zones/{zoneId}/rates | List shipping rates of a zone | |
POST | /stores/{storeRef}/shipping/calculate | Calculate shipping options | |
GET | /stores/{storeRef}/shipping/locations | List administrative areas |
write:analytics
| Method | Path | Summary | Also needs |
|---|---|---|---|
POST | /stores/{storeRef}/reports | Save a report | |
DELETE | /stores/{storeRef}/reports/{id} | Delete a saved report | |
PATCH | /stores/{storeRef}/reports/{id} | Update a saved report |
write:assets
| Method | Path | Summary | Also needs |
|---|---|---|---|
DELETE | /stores/{storeRef}/assets | Delete several assets | |
PUT | /stores/{storeRef}/assets/{assetId} | Update an asset | |
DELETE | /stores/{storeRef}/assets/{assetId} | Delete an asset | |
PUT | /stores/{storeRef}/assets/{assetId}/replace | Replace an asset's file | |
POST | /stores/{storeRef}/assets/from-canva | Create an asset from a Canva design | |
POST | /stores/{storeRef}/assets/links | Create or update asset links | |
DELETE | /stores/{storeRef}/assets/links | Remove asset links | |
POST | /stores/{storeRef}/assets/upload | Upload an asset | |
POST | /stores/{storeRef}/assets/videos/upload | Upload a video |
write:blog
write:categories
| Method | Path | Summary | Also needs |
|---|---|---|---|
POST | /stores/{storeRef}/collections | Create a collection | |
PUT | /stores/{storeRef}/collections/{id} | Update a collection | |
DELETE | /stores/{storeRef}/collections/{id} | Delete a collection | |
PUT | /stores/{storeRef}/collections/{id}/metafields | Set collection metafields | |
POST | /stores/{storeRef}/collections/{id}/products | Add products to a manual collection | |
DELETE | /stores/{storeRef}/collections/{id}/products | Remove products from a manual collection | |
PUT | /stores/{storeRef}/collections/{id}/products/reorder | Reorder a manual collection's products |
write:customers
| Method | Path | Summary | Also needs |
|---|---|---|---|
POST | /stores/{storeRef}/customers | Create a customer | |
DELETE | /stores/{storeRef}/customers/{customerId} | Delete a customer | |
PATCH | /stores/{storeRef}/customers/{customerId} | Update a customer | |
POST | /stores/{storeRef}/customers/{customerId}/addresses | Add a customer address | |
DELETE | /stores/{storeRef}/customers/{customerId}/addresses/{addressId} | Delete a customer address | |
PATCH | /stores/{storeRef}/customers/{customerId}/addresses/{addressId} | Update a customer address | |
PATCH | /stores/{storeRef}/customers/{customerId}/addresses/{addressId}/set-default | Set the default customer address | |
POST | /stores/{storeRef}/customers/{customerId}/merge | Merge two customers | |
PUT | /stores/{storeRef}/customers/{id}/metafields | Set customer metafields |
write:inventory
| Method | Path | Summary | Also needs |
|---|---|---|---|
POST | /stores/{storeRef}/inventory/import | Import stock quantities from CSV | |
POST | /stores/{storeRef}/inventory/levels/adjust | Adjust stock quantities | |
POST | /stores/{storeRef}/inventory/levels/move | Move stock between states | |
POST | /stores/{storeRef}/inventory/levels/set | Set stock quantities | |
PUT | /stores/{storeRef}/inventory/locations/{id}/metafields | Set inventory location metafields |
write:menus
| Method | Path | Summary | Also needs |
|---|---|---|---|
POST | /stores/{storeRef}/menus | Create a menu | |
PUT | /stores/{storeRef}/menus/{id} | Update a menu | |
DELETE | /stores/{storeRef}/menus/{id} | Delete a menu |
write:metafields
| Method | Path | Summary | Also needs |
|---|---|---|---|
POST | /stores/{storeRef}/metafield-definitions | Create a metafield definition | |
DELETE | /stores/{storeRef}/metafield-definitions/{id} | Delete a metafield definition | |
PATCH | /stores/{storeRef}/metafield-definitions/{id} | Update a metafield definition | |
PUT | /stores/{storeRef}/metafield-definitions/pins | Set pinned metafield definitions |
write:metaobjects
| Method | Path | Summary | Also needs |
|---|---|---|---|
POST | /stores/{storeRef}/metaobject-definitions | Create a metaobject definition | |
DELETE | /stores/{storeRef}/metaobject-definitions/{id} | Delete a metaobject definition | |
PATCH | /stores/{storeRef}/metaobject-definitions/{id} | Update a metaobject definition | |
POST | /stores/{storeRef}/metaobjects/{type}/entries | Create a metaobject entry | |
DELETE | /stores/{storeRef}/metaobjects/{type}/entries/{id} | Delete a metaobject entry | |
PATCH | /stores/{storeRef}/metaobjects/{type}/entries/{id} | Update a metaobject entry |
write:orders
| Method | Path | Summary | Also needs |
|---|---|---|---|
POST | /stores/{storeRef}/orders | Create an order | |
PUT | /stores/{storeRef}/orders/{id} | Update an order | |
DELETE | /stores/{storeRef}/orders/{id} | Cancel an order | |
PUT | /stores/{storeRef}/orders/{id}/deliver | Mark an order as delivered | |
PUT | /stores/{storeRef}/orders/{id}/fulfill | Mark an order as fulfilled | |
PUT | /stores/{storeRef}/orders/{id}/metafields | Set order metafields | |
PUT | /stores/{storeRef}/orders/{id}/resume | Resume an order from hold | |
PUT | /stores/{storeRef}/orders/{id}/ship | Mark an order as shipped | |
POST | /stores/{storeRef}/orders/{id}/shipments | Book a shipment | |
POST | /stores/{storeRef}/orders/{id}/shipments/{shipmentId}/cancel | Cancel a shipment | |
GET | /stores/{storeRef}/orders/{id}/shipments/{shipmentId}/label | Get a shipment label | |
POST | /stores/{storeRef}/orders/{id}/shipments/quote | Quote carrier services |
write:pages
| Method | Path | Summary | Also needs |
|---|---|---|---|
POST | /stores/{storeRef}/content-pages | Create a content page | |
PUT | /stores/{storeRef}/content-pages/{id} | Update a content page | |
DELETE | /stores/{storeRef}/content-pages/{id} | Delete a content page | |
POST | /stores/{storeRef}/content-pages/{id}/duplicate | Duplicate a content page | |
PUT | /stores/{storeRef}/content-pages/{id}/metafields | Set content page metafields | |
POST | /stores/{storeRef}/content-pages/{id}/preview-token | Create a content page preview link |
write:products
write:promotions
| Method | Path | Summary | Also needs |
|---|---|---|---|
POST | /stores/{storeRef}/promotions | Create a promotion | |
PUT | /stores/{storeRef}/promotions/{id} | Update a promotion's status | |
DELETE | /stores/{storeRef}/promotions/{id} | Delete a promotion |
write:purchase_orders
| Method | Path | Summary | Also needs |
|---|---|---|---|
POST | /stores/{storeRef}/purchase-orders | Create a purchase order | |
PUT | /stores/{storeRef}/purchase-orders/{id} | Update a purchase order | |
DELETE | /stores/{storeRef}/purchase-orders/{id} | Delete a purchase order | |
POST | /stores/{storeRef}/purchase-orders/{id}/cancel | Cancel a purchase order | |
POST | /stores/{storeRef}/purchase-orders/{id}/close | Close a purchase order | |
POST | /stores/{storeRef}/purchase-orders/{id}/order | Mark a purchase order as ordered | |
POST | /stores/{storeRef}/purchase-orders/{id}/receipts | Receive units on a purchase order | |
POST | /stores/{storeRef}/purchase-orders/{id}/send | Email a purchase order to its supplier | |
POST | /stores/{storeRef}/suppliers | Create a supplier | |
PUT | /stores/{storeRef}/suppliers/{id} | Update a supplier | |
DELETE | /stores/{storeRef}/suppliers/{id} | Delete a supplier | |
POST | /stores/{storeRef}/suppliers/{id}/archive | Archive a supplier | |
POST | /stores/{storeRef}/suppliers/{id}/unarchive | Unarchive a supplier |
write:reviews
| Method | Path | Summary | Also needs |
|---|---|---|---|
POST | /stores/{storeRef}/reviews | Create a review | |
PUT | /stores/{storeRef}/reviews/{reviewId} | Update a review | |
DELETE | /stores/{storeRef}/reviews/{reviewId} | Delete a review | |
POST | /stores/{storeRef}/reviews/{reviewId}/replies | Reply to a review | |
PUT | /stores/{storeRef}/reviews/{reviewId}/replies/{replyId} | Update a reply | |
DELETE | /stores/{storeRef}/reviews/{reviewId}/replies/{replyId} | Delete a reply | |
POST | /stores/{storeRef}/reviews/bulk-import | Import reviews in bulk | |
PUT | /stores/{storeRef}/reviews/bulk-moderate | Approve or reject reviews in bulk |
write:settings
write:shippings
| Method | Path | Summary | Also needs |
|---|---|---|---|
POST | /stores/{storeRef}/shipping-zones | Create a shipping zone | |
PUT | /stores/{storeRef}/shipping-zones/{id} | Update a shipping zone | |
DELETE | /stores/{storeRef}/shipping-zones/{id} | Delete a shipping zone | |
POST | /stores/{storeRef}/shipping-zones/{zoneId}/rates | Create a shipping rate | |
PUT | /stores/{storeRef}/shipping-zones/{zoneId}/rates/{id} | Update a shipping rate | |
DELETE | /stores/{storeRef}/shipping-zones/{zoneId}/rates/{id} | Delete a shipping rate |
Any secret key for the store
| Method | Path | Summary | Also needs |
|---|---|---|---|
GET | /stores | List stores | |
GET | /stores/{storeRef} | Get a store | |
GET | /stores/{storeRef}/search/admin | Search orders, customers and products | |
GET | /themes | List catalog themes |
Reference built from Store API 3.49.0, Storefront API 3.49.0, @ecomweb/sdk 0.14.1 and @ecomweb/storefront-kit 0.14.1.