Shopify API access scopes

All apps need to request access to specific store data during the app authorization process. This guide provides a list of available access scopes for the GraphQL Admin, Storefront, Payment Apps APIs, and Customer Account APIs.

Anchor to How it worksHow it works

After you've generated API credentials, your app needs to be authorized to access store data.

Authorization is the process of giving permissions to apps. Users can authorize Shopify apps to access data in a store. For example, an app might be authorized to access orders and product data in a store.

An app can request authenticated or unauthenticated access scopes. Any permission to write a resource includes permission to read it, so request the write scope only when your app needs both.

Anchor to Authenticated access scopesAuthenticated access scopes

This section describes the authenticated access scopes that your app can request. In the table, access to some resources are marked with permissions required. In these cases, you must request specific permission to access data from the user in your Partner Dashboard.

Anchor to Requesting specific permissionsRequesting specific permissions

Follow the procedures below to request specific permissions for access scopes. Most permissions are requested in the Partner Dashboard, but some require contacting Shopify Support.

Anchor to Orders permissionsOrders permissions

By default, you have access to the last 60 days' worth of orders for a store. To access all the orders, you need to request access to the read_all_orders scope from the user:

1. From the Partner Dashboard, go to Apps.
2. Click the name of your app.
3. Click API access.
4. In the Access requests section, on the Read all orders scope card, click Request access.
5. On the Orders page that opens, describe your app and why you're applying for access.
6. Click Request access.

If Shopify approves your request, then you can add the read_all_orders scope to your app along with read_orders or write_orders.

Anchor to Subscription APIs permissionsSubscription APIs permissions

Subscription apps let users sell subscription products that generate multiple orders on a specific billing frequency.

With subscription products, the app user isn't required to get customer approval for each subsequent order after the initial subscription purchase. As a result, your app needs to request the required protected access scopes to use Subscription APIs from the app user:

1. From the Partner Dashboard, go to Apps.
2. Click the name of your app.
3. Click API access.
4. In the Access requests section, on the Access Subscriptions APIs card, click Request access.
5. On the Subscriptions page that opens, describe why you're applying for access.
6. Click Request access.

If Shopify approves your request, then you can add the read_customer_payment_methods and write_own_subscription_contracts scopes to your app. If you're using the Customer Account API, you can add the customer_read_own_subscription_contracts or customer_write_own_subscription_contracts scopes.

Anchor to Shopify Payments dispute evidence permissionsShopify Payments dispute evidence permissions

The read_shopify_payments_dispute_evidences, write_shopify_payments_dispute_evidences, read_shopify_payments_dispute_file_uploads, and write_shopify_payments_dispute_file_uploads scopes are restricted. Shopify grants these scopes to individual apps. To be eligible:

• Your app must use public distribution
• Dispute or chargeback management must be a core part of what your app does. Apps outside the dispute space aren't granted these scopes

You can't add these scopes to your app configuration until Shopify approves your app for them. If you declare one before approval, then creating an app version fails with an app_access validation error on scopes.

To request access, contact Shopify Support and describe your app and why it needs to read or submit dispute evidence.

Anchor to Protected customer data permissionsProtected customer data permissions

By default, apps don't have access to any protected customer data. To access protected customer data, you must meet our protected customer data requirements. You can add the relevant scopes to your app, but the API won't return data from non-development stores until your app is configured and approved for protected customer data use.

Anchor to Unauthenticated access scopesUnauthenticated access scopes

Unauthenticated access scopes provide apps with read-only access to the Storefront API. Unauthenticated access is intended for interacting with a store on behalf of a customer. For example, an app might need to do one or more of following tasks:

• Read products and collections
• Create customers and update customer accounts
• Query international prices for products and orders
• Interact with a cart during a customer's session
• Initiate a checkout

Anchor to Request scopesRequest scopes

To request unauthenticated access scopes for an app, select them when you generate API credentials or change granted access scopes.

To request access scopes or permissions for the Headless channel, refer to managing the Headless channel.

You can request the following unauthenticated access scopes:

Anchor to Customer access scopesCustomer access scopes

Customer access scopes provide apps with read and write access to the Customer Account API. Customer access is intended for interacting with data that belongs to a customer. For example, an app might need to do one or more of following tasks:

• Read customers orders
• Update customer accounts
• Create and update customer addresses
• Read shop, customer or order metafields

Anchor to Request scopesRequest scopes

To request access scopes or permissions for the Headless or Hydrogen channel, refer to managing permissions.

You can request the following customer access scopes:

Anchor to Checking granted access scopesChecking granted access scopes

You can check your app's granted access scopes using the appInstallation query in the GraphQL Admin API.

Anchor to LimitationsLimitations

• Apps should request only the minimum amount of data that's necessary for an app to function when using a Shopify API. Shopify restricts access to scopes for apps that don't require legitimate use of the associated data.
• Only public or custom apps are granted access scopes. Legacy app types, such as private or unpublished, won't be granted new access scopes.