Enable extension capabilities for checkout

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 four capabilities enabled:

Anchor to Storefront API accessStorefront API access

The following section describes the use cases of the api_access capability and the Storefront API access scopes.

SeeAPI access examples

Anchor to When to use Storefront API accessWhen to use Storefront API access

API access is used when your extension needs to retrieve data from the Storefront API. For example, you may need to fetch product data, check the product tags on an item in the cart, or convert a product's price to another currency.

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

Enabling the api_access capability allows you to use the checkout Storefront API query method and the global fetch to retrieve data from the Storefront API without manually managing token acquisition and refresh.

query lets you request a single GraphQL response from the Storefront API.

If you prefer to construct GraphQL requests yourself or you would like to use a full-featured GraphQL client such as Apollo or urql, our custom fetch global automatically appends the required access tokens.

The GraphQL client of your choice shouldn’t use any DOM APIs, as they aren’t available in a checkout UI extension's Web Worker.

Anchor to Storefront API access scopesStorefront API access scopes

Your extensions will have the following unauthenticated access scopes to the Storefront API:

• unauthenticated_read_product_publications
• unauthenticated_read_collection_publications
• unauthenticated_read_product_listings
• unauthenticated_read_product_tags
• unauthenticated_read_selling_plans
• unauthenticated_read_collection_listings
• unauthenticated_read_metaobjects

Anchor to Protocol LinksProtocol Links

Protocol links are an easy way for Shopify to infer the type of request you are trying to make. If you would like to make a request to the Storefront GraphQL API, you can use our Storefront Protocol to infer your Storefront URL and API version.

Anchor to Network accessNetwork access

The following section describes use cases for requesting network access, alternatives to requesting network access, and steps for completing a request for network access.

Anchor to When to request network accessWhen to request network access

If you need to get data into checkout that you can't currently get from Shopify, then you should request network access. For example, you might need to fetch additional data to render loyalty points.

Anchor to Alternatives to network accessAlternatives to network access

Instead of fetching data with an external network call, consider retrieving the data from a metafield. Your app may be able to use the GraphQL Admin API to write metafields on the shop, product, or customer ahead of checkout.

Retrieving data from metafields during checkout is faster since it won't introduce an external network call. This allows you to rely on Shopify for the uptime, scaling, and durability of the data storage.

Anchor to Complete a request for network accessComplete a request for 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 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 checkout UI extension to make external network calls.

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

Anchor to Required CORS headersRequired CORS headers

UI extensions run in a Web Worker but the exact origin they run on may change without notice. When receiving network requests from extensions, your server must support cross-origin resource sharing (CORS) for any origin by always returning this response header:

Anchor to Security considerationsSecurity considerations

When processing HTTP requests on your API server, you cannot guarantee that your own extension will have 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 does not 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 could not trust a ?customer_id= query parameter.

Consider a scenario where your extension retrieves a discount code from your API server and applies it to the checkout. It would not be safe to expose an API endpoint named /get-discount-code if any buyer could make a direct HTTP request and obtain a discount code.

Anchor to App ProxyApp Proxy

UI extensions can make fetch requests to App Proxy URLs, but there are some differences and limitations related to the security context within which UI extensions run.

UI extension requests made to the App Proxy will execute as CORS requests. See Required CORS headers above for information about requirements related to CORS.

UI extension requests made to the App Proxy will not assign the logged_in_customer_id query parameter. Instead use a session token which provides the sub claim for the logged in customer.

UI extension requests made to the App Proxy of password protected shops is not supported. Extension requests come from a web worker which does not share the same session as the parent window.

The App Proxy doesn't handle all HTTP request methods. Specifically, CONNECT and TRACE are unsupported.

Anchor to Block progressBlock progress

The following section describes blocking the buyer's progress through checkout, and how you can detect whether the merchant has allowed it.

SeeBlocking examples

Anchor to When to request blocking progressWhen to request blocking progress

If your extension relies on specific input then you might need to block the buyer's progress until they've provided all required information. You can do this with a buyer journey intercept, by returning behavior: 'block'.

For example, for some purchases you need to collect and verify a customer's age. For the order to be valid, you need to verify that an age is set and that it's greater than or equal to a minimum value.

In order to block checkout progress, your extension must have the block_progress capability.

Anchor to Granting the capability to block progressGranting the capability to block progress

Setting block_progress in the shopify.extension.toml file informs merchants that your extension blocks the buyer's progress for invalid orders. Merchants can allow or disallow this capability in the checkout editor.

Anchor to Detecting the ability to block progressDetecting the ability to block progress

In your extension, look for block_progress in extension.capabilities to see if the merchant has granted the blocking capability.

If the merchant declined the permission for your app to block progress, the behavior: 'block' option in the buyer journey intercept will be treated as behavior: 'allow', and checkout will proceed as normal.

When developing a local extension, you can remove the block_progress capability from your shopify.extension.toml file to simulate a merchant disallowing the capability.

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