Skip to main content

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.


Tip

For more information on how to configure your access scopes, refer to app configuration and manage access scopes.

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 scopesDescriptionExample use cases
AuthenticatedControls access to resources in the GraphQL Admin API, Web Pixel API, and Payments Apps API.
Authenticated access is intended for interacting with a store on behalf of a user.
  • Creating products
  • Managing discount codes
UnauthenticatedControls an app's access to Storefront API objects.
Unauthenticated access is intended for interacting with a store on behalf of a customer.
  • Viewing products
  • Initiating a checkout
CustomerControls an app's access to Customer Account API objects.
Customer access is intended for interacting with data that belongs to a customer.
  • Viewing orders
  • Updating customer details

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.

Info

To authenticate an admin-created custom app, you or the app user needs to install the app from the Shopify admin to generate API credentials and the necessary API access tokens. Refer to access scopes for admin-created custom apps.

Authenticated access scopes
ScopeAccess
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 read_orders or write_orders.

You need to request permission for this access scope from your Partner Dashboard before adding it to your app.

write_app_proxy

Allows your app to use app proxies.

read_assigned_fulfillment_orders,

write_assigned_fulfillment_orders,

read_merchant_managed_fulfillment_orders,

write_merchant_managed_fulfillment_orders,

read_third_party_fulfillment_orders,

write_third_party_fulfillment_orders,

read_marketplace_fulfillment_orders

FulfillmentOrder

As of API version 2024-10, write_third_party_fulfillment_orders will no longer allow order management apps to create fulfillments for fulfillment orders that have been assigned to a different fulfillment service app.

read_cart_transforms,

write_cart_transforms

CartTransform

read_checkout_branding_settings,

write_checkout_branding_settings

CheckoutBranding

read_content,

write_content,

read_online_store_pages

Article, Blog, Comment, Page

read_customer_events,

write_pixels

Web Pixels API

read_customer_merge,

write_customer_merge

CustomerMergePreview, CustomerMergeRequest

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_customers,

write_customers

Customer, Segment, Company, CompanyLocation

read_delivery_customizations,

write_delivery_customizations

DeliveryCustomization

read_discounts,

write_discounts

Discounts features

read_draft_orders,

write_draft_orders

DraftOrder

read_files,

write_files

GenericFile

read_fulfillments,

write_fulfillments

FulfillmentService

read_gift_cards,

write_gift_cards

GiftCard

read_inventory,

write_inventory

InventoryLevel, InventoryItem

read_legal_policies

ShopPolicy

read_locales,

write_locales

ShopLocale

read_locations,

write_locations

Location

read_markets,

write_markets

Market

read_marketing_events,

write_marketing_events

MarketingEvent, MarketingActivity
read_merchant_approval_signalsMerchantApprovalSignals

read_metaobject_definitions,

write_metaobject_definitions

MetaobjectDefinition

read_metaobjects,

write_metaobjects

Metaobject

read_online_store_navigation

write_online_store_navigation

UrlRedirect

read_order_edits,

write_order_edits

CalculatedOrder, DeliveryCarrierService

read_orders,

write_orders

AbandonedCheckout, Fulfillment, Order, OrderTransaction, DeliveryCarrierService

read_own_subscription_contracts,

write_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_payment_customizations,

write_payment_customizations

PaymentCustomization

read_payment_gateways,

write_payment_gateways

Payments Apps API PaymentsAppConfiguration

read_payment_mandate,

write_payment_mandate

PaymentMandate
write_payment_sessionsPayments Apps API PaymentSession, CaptureSession, RefundSession, VoidSession

read_payment_terms,

write_payment_terms

PaymentSchedule, PaymentTerms

read_price_rules,

write_price_rules

PriceRule

write_privacy_settings,

read_privacy_settings

CookieBanner, PrivacySettings

read_products,

write_products

Product, ProductVariant, Collection, ResourceFeedback

read_purchase_options,

write_purchase_options

SellingPlan

read_returns,

write_returns

Return

read_script_tags,

write_script_tags

ScriptTag

read_shipping,

write_shipping

DeliveryCarrierService
read_shopify_payments_disputesShopifyPaymentsDispute
read_shopify_payments_dispute_evidencesShopifyPaymentsDisputeEvidence
read_shopify_payments_payoutsShopifyPaymentsPayout, ShopifyPaymentsBalanceTransaction
read_store_credit_accountsStoreCreditAccount

read_store_credit_account_transactions,

write_store_credit_account_transactions

StoreCreditAccountDebitTransaction, StoreCreditAccountCreditTransaction

read_themes,

write_themes

OnlineStoreTheme
read_translationsTranslatableResource
read_usersStaffMembershopify plus

read_validations,

write_validations

Validation

Anchor to Requesting specific permissionsRequesting specific permissions

Follow the procedures below to request specific permissions to request access scopes in the Partner Dashboard.

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 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

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:

Unauthenticated access scopes
ScopeAccess
unauthenticated_read_checkouts,
unauthenticated_write_checkouts
Checkout object
unauthenticated_read_customers,
unauthenticated_write_customers
Customer object
unauthenticated_read_customer_tagstags field on the Customer object
unauthenticated_read_contentStorefront content, such as Article, Blog, and Comment objects
unauthenticated_read_metaobjectsView metaobjects, such as Metaobject
unauthenticated_read_product_inventoryquantityAvailable field on the ProductVariant object and totalAvailable field on the Product object
unauthenticated_read_product_listingsProduct and Collection objects
unauthenticated_read_product_pickup_locationsLocation and StoreAvailability objects
unauthenticated_read_product_tagstags field on the Product object
unauthenticated_read_selling_plansSelling plan content on the Product object

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

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

You can request the following customer access scopes:

Customer access scopes
ScopeAccess
customer_read_customers,
customer_write_customers
Customer object
customer_read_orders,
customer_write_orders
Order object
customer_read_draft_ordersDraft Order object
customer_read_marketsMarket object
customer_read_store_credit_accountsStore Credit Account object
customer_read_own_subscription_contracts,
customer_write_own_subscription_contracts
Subscription Contract object for records that belong to your app
customer_write_subscription_contractsSubscription Contract object for all records. Only available for Hydrogen and Headless storefronts
customer_read_companies,
customer_write_companies
Company object
customer_read_locations,
customer_write_locations
Company Location object

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 Limitations and considerationsLimitations 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.

Was this page helpful?