Shopify API access scopes
All apps need to request access to specific store data during the app authorization process. This guide provides a complete list of available access scopes for the Admin, Storefront, and Payment Apps APIs.
How it works
Anchor link to section titled "How 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.
Type of access scopes | Description | Example use cases |
---|---|---|
Authenticated | Controls access to resources in the REST Admin API, GraphQL Admin API, and Payments Apps API. Authenticated access is intended for interacting with a store on behalf of a user. |
|
Unauthenticated | Controls an app's access to Storefront API objects. Unauthenticated access is intended for interacting with a store on behalf of a customer. |
|
Customer | Controls an app's access to Customer Account API objects. Customer access is intended for interacting with data that belongs to a customer. |
|
Authenticated access scopes
Anchor link to section titled "Authenticated access scopes"Your app can request the following authenticated access scopes:
Scope | Access |
---|---|
read_all_orders |
All relevant orders rather than the default window of orders created within the last 60 daysPermissions required This access scope is used in conjunction with existing order scopes, for example You need to request permission for this access scope from your Partner Dashboard before adding it to your app. |
read_assigned_fulfillment_orders ,
|
FulfillmentOrder resources assigned to a location managed by your fulfillment service |
read_cart_transforms ,
|
Manage Cart Transform objects to sell bundles. |
read_checkouts ,
|
Checkouts |
read_checkout_branding_settings ,
|
Checkout branding |
read_content ,
|
Article, Blog, Comment, Page, Redirects, and Metafield Definitions |
read_customer_merge ,
|
CustomerMergePreview and CustomerMergeRequest |
read_customers ,
|
Customer and Saved Search |
read_customer_payment_methods |
CustomerPaymentMethodPermissions required You need to request permission for this access scope from your Partner Dashboard before adding it to your app. |
read_delivery_customizations ,
|
DeliveryCustomization |
read_discounts ,
|
GraphQL Admin API Discounts features |
read_draft_orders ,
|
Draft Order |
read_files ,
|
GraphQL Admin API GenericFile object and fileCreate, fileUpdate, and fileDelete mutations |
read_fulfillments ,
|
Fulfillment Service |
read_gift_cards ,
|
Gift Card |
read_inventory ,
|
Inventory Level and Inventory Item |
read_legal_policies |
GraphQL Admin API Shop Policy |
read_locales ,
|
GraphQL Admin API Shop Locale |
write_locations |
GraphQL Admin API locationActivate, locationAdd, locationDeactivate, locationDelete, and locationEdit mutations. |
read_locations |
Location |
read_markets ,
|
Market |
read_metaobject_definitions ,
|
MetaobjectDefinition |
read_metaobjects ,
|
Metaobject |
read_marketing_events ,
|
Marketing Event |
read_merchant_approval_signals |
MerchantApprovalSignals |
read_merchant_managed_fulfillment_orders ,
|
FulfillmentOrder resources assigned to merchant-managed locations |
read_orders ,
|
Abandoned checkouts, Customer, Fulfillment, Order, and Transaction resources |
read_payment_mandate ,
|
PaymentMandate |
read_payment_terms ,
|
GraphQL Admin API PaymentSchedule and PaymentTerms objects |
read_price_rules ,
|
Price Rules |
read_products ,
|
Product, Product Variant, Product Image, Collect, Custom Collection, and Smart Collection |
read_product_listings |
Product Listing and Collection Listing |
read_publications ,
|
Product publishing and Collection publishing |
read_purchase_options ,
|
SellingPlan |
read_reports ,
|
Reports |
read_resource_feedbacks ,
|
ResourceFeedback |
read_script_tags ,
|
Script Tag |
read_shipping ,
|
Carrier Service, Country, and Province |
read_shopify_payments_disputes |
Shopify Payments Dispute resource. GraphQL Admin API ShopifyPaymentsDispute object. |
read_shopify_payments_dispute_evidences |
Shopify Payments Dispute Evidence resource. GraphQL Admin API ShopifyPaymentsDisputeEvidence object. |
read_shopify_payments_payouts |
Shopify Payments Payouts, Balance, and Transaction resources |
read_store_credit_accounts |
StoreCreditAccount |
read_store_credit_account_transactions ,
|
StoreCreditAccountDebitTransaction and StoreCreditAccountCreditTransaction |
read_own_subscription_contracts ,
|
GraphQL Admin API SubscriptionContractPermissions requiredCustomer Account API SubscriptionContractPermissions required You need to request permission for these access scopes from your Partner Dashboard before adding them to your app. |
read_returns ,
|
Return object |
read_themes ,
|
Asset and Theme |
read_translations ,
|
GraphQL Admin API Translatable object |
read_third_party_fulfillment_orders ,
|
FulfillmentOrder resources assigned to a location managed by any fulfillment service. |
read_users |
User and StaffMemberSHOPIFY PLUS |
read_order_edits ,
|
GraphQL Admin API OrderStagedChange types and order editing features |
write_payment_gateways |
Payments Apps API paymentsAppConfigure |
write_payment_sessions |
Payments Apps API Payment, Capture, Refund and Void |
write_pixels ,
|
Web Pixels API |
write_privacy_settings ,
|
GraphQL Admin API CookieBanner, PrivacySettings objects and consentPolicyUpdate, dataSaleOptOut mutations |
read_validations ,
|
GraphQL Admin API Validation object |
Requesting specific permissions
Anchor link to section titled "Requesting specific permissions"Follow the procedures below to request specific permissions to request access scopes in the Partner Dashboard.
Orders permissions
Anchor link to section titled "Orders 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:
- From the Partner Dashboard, go to Apps.
- Click the name of your app.
- Click API access.
- In the Access requests section, on the Read all orders scope card, click Request access.
- On the Orders page that opens, describe your app and why you’re applying for access.
- 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
.
Subscription APIs permissions
Anchor link to section titled "Subscription 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:
- From the Partner Dashboard, go to Apps.
- Click the name of your app.
- Click API access.
- In the Access requests section, on the Access Subscriptions APIs card, click Request access.
- On the Subscriptions page that opens, describe why you’re applying for access.
- 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.
Protected customer data permissions
Anchor link to section titled "Protected 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.
Unauthenticated access scopes
Anchor link to section titled "Unauthenticated 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
Request scopes
Anchor link to section titled "Request 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:
Scope | Access |
---|---|
unauthenticated_read_checkouts ,
|
Checkout object |
unauthenticated_read_customers ,
|
Customer object |
unauthenticated_read_customer_tags |
tags field on the Customer object |
unauthenticated_read_content |
Storefront content, such as Article, Blog, and Comment objects |
unauthenticated_read_metaobjects |
View metaobjects, such as Metaobject |
unauthenticated_read_product_inventory |
quantityAvailable field on the ProductVariant object and totalAvailable field on the Product object |
unauthenticated_read_product_listings |
Product and Collection objects |
unauthenticated_read_product_pickup_locations |
Location and StoreAvailability objects |
unauthenticated_read_product_tags |
tags field on the Product object |
unauthenticated_read_selling_plans |
Selling plan content on the Product object |
Customer access scopes
Anchor link to section titled "Customer 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
Request scopes
Anchor link to section titled "Request 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:
Scope | Access |
---|---|
customer_read_customers ,
|
Customer object |
customer_read_orders |
Order object |
customer_read_draft_orders |
Draft Order object |
customer_read_markets |
Market object |
customer_read_store_credit_accounts |
Store Credit Account object |
customer_read_own_subscription_contracts ,
|
Subscription Contract object for records that belong to your app |
customer_write_subscription_contracts |
Subscription Contract object for all records. Only available for Hydrogen and Headless storefronts |
Checking granted access scopes
Anchor link to section titled "Checking granted access scopes"You can check your app’s granted access scopes using the GraphQL Admin API or REST Admin API.
Limitations and considerations
Anchor link to section titled "Limitations and considerations"- 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.