API access scopes

Scopes are the permissions your app asks for during installation. You list them in the scope parameter of the authorize URL, separated by commas, and the merchant approves them on the consent page. Your access token can then only call the APIs those scopes allow.

{host_url}/oauth/authorize?client_id={client_id}&scope=read_products,write_products&redirect_uri={redirect_uri}
  • Ask only for what you need. Merchants see every permission before they install.
  • write_* scopes don't include read access. Request read_* as well if your app reads the same data.
  • A scope that isn't in the list below is rejected, and installation fails with "Invalid scopes".
  • A call without the right scope fails with permission_denied.
  • Every app can read basic store information (GET /store.json) and manage its own webhooks without an extra scope.

Available scopes

Scopes Gives access to
read_products
write_products
Products and variants, product images, collections, collects, and inventory levels (API 4.0)
read_orders
write_orders
Orders, transactions, checkouts, and returns (API 4.0)
read_fulfillments
write_fulfillments
Fulfillments of orders, including tracking details and shipment status
read_customers
write_customers
Customers, customer addresses, customer groups, store credit and points
read_customer_attributes
write_customer_attributes
Customer custom attributes
read_content
write_content
Pages, blogs, articles, navigations and redirects
read_snippets
write_snippets
Snippets
read_script_tags
write_script_tags
Script tags
read_shipping
write_shipping
Shipping rate curls (shipping/list/cod, shipping/list/non_cod) for logistic apps
read_locations
write_locations
Store locations, and pickup curls (pickup/locations/list, pickup/methods/list)
read_currencies
write_currencies
Store currencies
write_resource_feedbacks Resource feedbacks (API 4.0)

Which scopes do I need?

Typical scopes for common kinds of apps:

Your app Scopes
Storefront widget (badge, recommendations, chat) read_products, write_snippets or write_script_tags
ERP, inventory or warehouse sync read_products, write_products, read_orders, read_locations; add write_fulfillments if you ship orders
Logistics or courier read_orders, read_fulfillments, write_fulfillments, write_shipping; add write_locations for pickup points
CRM, email marketing or loyalty read_customers, write_customers, read_orders
Accounting or reporting read_orders, read_products, read_customers

See Popular APIs for what each API can do.

icon-accounticon-add-newicon-add-storeicon-appicon-appleicon-archiveicon-arrowdownicon-ascicon-bookicon-cancelicon-cart-addonicon-checkouticon-cherryicon-collectionicon-comfirmicon-confirmicon-couponicon-creditsicon-currencyicon-dashboardicon-discounticon-disintegrateicon-domainicon-dscicon-duplicateicon-editicon-emailicon-exclamation-triangleicon-exporticon-eyeicon-eye-slashicon-fullscreenicon-fullscreen-closeicon-generalicon-gifticon-gridicon-hddicon-helpicon-importicon-infoicon-integrationicon-invoiceicon-likeicon-listicon-locationicon-logouticon-new-tabicon-not-secureicon-optionicon-ordericon-outline-arrowdownicon-pageicon-paymenticon-plusicon-posicon-pricingicon-printericon-producticon-product-sumicon-product-sum-xicon-redirecticon-reporticon-reseticon-searchicon-secureicon-settingicon-shippingicon-staricon-storeicon-switch-storeicon-tagicon-taxesicon-templateicon-themeicon-tickicon-trashicon-unarchiveicon-uploadicon-user-tagicon-usersicon-weighticon-wholesale