Enable extension capabilities for customer accounts

Capabilities are permissions you declare in your extension's shopify.extension.toml file. They control what your extension is allowed to do at a platform level, such as querying the Storefront API, making external network calls, or collecting buyer consent.

Anchor to Available capabilitiesAvailable capabilities

The following example shows a complete shopify.extension.toml file with all three capabilities enabled:

Anchor to Storefront API accessStorefront API access

Use the api_access capability when your extension needs to retrieve data from the Storefront API. For example, you might need to fetch product data, check product tags on an item in the order summary, or look up selling plans.

Shopify handles the authentication for all API calls from an extension.

Anchor to Enable Storefront API accessEnable Storefront API access

Anchor to Methods for accessing the Storefront APIMethods for accessing the Storefront API

Enabling api_access allows you to retrieve data from the Storefront API without manually managing token acquisition and refresh.

Use the query method to request a single GraphQL response from the Storefront API. This is the recommended approach for most use cases and is available on all customer account targets.

If you prefer to construct GraphQL requests yourself or use a full-featured GraphQL client such as Apollo or urql, you can use the global fetch instead. The custom fetch global automatically appends the required access tokens. The GraphQL client of your choice shouldn't use any DOM APIs, because they aren't available in a customer account UI extension's Web Worker.

Anchor to Storefront API access scopesStorefront API access scopes

Your extension automatically receives unauthenticated read access to products, collections, product tags, selling plans, and metaobjects through the Storefront API. For the full list of access scopes, refer to the Storefront API documentation.

ReferenceStorefront API

Anchor to Network accessNetwork access

Use the network_access capability when you need data that isn't available through Shopify's APIs. For example, you might need to fetch loyalty points from your rewards platform, pull inventory status from a warehouse management system, or send analytics events to a third-party service.

Anchor to Alternatives to network accessAlternatives to network access

Before requesting network access, consider retrieving data from a metafield instead. This avoids external network calls and relies on Shopify for uptime, scaling, and durability. Depending on where your data lives and when you need it, you can use one of these approaches:

• Read and write customer, order, company, or company location data: Use the Customer Account API to access metafields directly from your extension.
• Read shop or product data written ahead of time: Use the GraphQL Admin API to write metafields before the customer visits the page, then read them from your extension.
• Read metafields on order status targets without a network call: Use appMetafields to retrieve metafields that are already available through Shopify. This is faster because there's no external request.

Anchor to Request network accessRequest network access

1. Go to your Partner Dashboard.

2. Click the name of the app that you want to change.

3. Click API access.

4. Under Allow network access in checkout and account UI extensions, click Allow network access.

   Your request is automatically approved and your app is immediately granted the approval scope that's required for your customer account UI extension to make external network calls.

5. Add network_access = true to the [extensions.capabilities] section of your extension's configuration file:

   shopify.extension.toml

   Copy

   9

   1

   2

   [extensions.capabilities]

   network_access = true

Anchor to Required CORS headersRequired CORS headers

Customer account UI extensions run in a sandboxed Web Worker, not in the browser page itself. This means network requests from your extension don't carry a recognizable origin. For your server to accept these requests, it must include the following CORS response header:

Anchor to App ProxyApp Proxy

App Proxy lets you route requests through Shopify to your app's backend. UI extensions can make fetch requests to App Proxy URLs, but there are some differences and limitations because extensions run in a Web Worker:

• Requests execute as CORS requests. See Required CORS headers for details.
• The logged_in_customer_id query parameter isn't assigned. Use a session token instead, which provides the sub claim for the logged-in customer.
• Requests to password-protected shops aren't supported. Extension requests come from a Web Worker which doesn't share the same session as the parent window.
• Not all HTTP request methods are supported. Specifically, CONNECT and TRACE are unsupported.

Anchor to Security considerationsSecurity considerations

When processing HTTP requests on your API server, you can't guarantee that your own extension made every request. When responding with sensitive data, keep in mind that requests could originate from anywhere on the internet.

Your extension can pass a session token to your API server, but this only guarantees the integrity of its claims. It doesn't guarantee the request itself originated from Shopify. For example, your API server could trust the session token's sub claim (the customer ID) but it couldn't trust a ?customer_id= query parameter.

Anchor to Collect buyer consentCollect buyer consent

Use the collect_buyer_consent capability when your extension applies consent changes. This capability is required before your extension can call applyTrackingConsentChange() or use the consent checkbox and consent phone field components. Reading consent state from shopify.customerPrivacy does not require this capability.

Shopify manages a consent state for each visitor that tracks preferences across categories, including analytics, marketing, preferences, and sale of data. When you enable collect_buyer_consent, your extension can participate in this system by reading the current consent state and applying updates.

Anchor to How consent state worksHow consent state works

Shopify tracks each visitor's consent decisions for analytics, marketing, preferences, and data sale. When a visitor hasn't made a decision yet, your extension can present a consent banner and record their choices.

Read the current state from shopify.customerPrivacy.value:

• saleOfDataRegion: Set to true when the visitor's region requires sale-of-data opt-out controls.
• shouldShowBanner: Set to true when the visitor hasn't made a consent decision yet. Check this before rendering a banner.
• visitorConsent: The visitor's current choices for analytics, marketing, preferences, and saleOfData.

Save the visitor's choices with shopify.applyTrackingConsentChange(). Shopify applies these decisions across all Shopify-managed services.

Anchor to SMS marketing consentSMS marketing consent

Add sms_marketing = true to use the consent checkbox and consent phone field components. Set the policy attribute to sms-marketing on those components.

Anchor to Customer privacy consentCustomer privacy consent

Add customer_privacy = true to use the Customer Privacy API for collecting cookie and tracking consent.

Anchor to Enable consent collectionEnable consent collection

ReferenceCustomer Privacy API