Configuration
When you create a checkout UI extension, the shopify.ui.extension.toml
file is automatically generated in your checkout UI extension directory. This guide describes the properties that you can configure in shopify.ui.extension.toml
.
Anchor to how-it-worksHow it works
You define properties for your checkout UI extension in the extension configuration file. The shopify.ui.extension.toml
file contains the extension's configuration, which include the extension name, extension points, metafields, capabilities, and settings definition.
When an extension is published to Shopify, the contents of the settings file are pushed alongside the extension.
Shopify Checkout UI scaffolding
shopify.ui.extension.toml
examples
Shopify Checkout UI scaffolding
shopify.ui.extension.toml
type = "checkout_ui_extension" name = "my-checkout-extension" extension_points = [ 'Checkout::Dynamic::Render' ] [[metafields]] namespace = "my-namespace" key = "my-key" [[metafields]] namespace = "my-namespace" key = "my-other-key" [capabilities] network_access = true block_progress = true api_access = true [settings] [[settings.fields]] key = "field_key" type = "boolean" name = "field-name" [[settings.fields]] key = "field_key_2" type = "number_integer" name = "field-name-2"
Anchor to configuration-propertiesConfiguration properties
Property | Required? | Description |
---|---|---|
type | Yes | The type of extension. For checkout UI extensions, this value is . |
name | Yes | The name of the checkout UI extension. |
| Yes | The pre-defined points within checkout that your extension will render to. These values must match how your extension calls extend() or render() .For example, if your extension calls extend('Checkout::Dynamic::Render', () => {}) then your config must specify Checkout::Dynamic::Render . |
metafields | Yes | The metafields that your extension needs to read. You can specify up to five key and namespace pairs in the settings file. When the extension is executed, Shopify looks for the metafields in each resource and returns their contents. |
capabilities | No | Defines the capabilities associated with the UI extension. |
settings | No | Defines settings that a merchant can set values for in the checkout editor. |
Anchor to api-accessStorefront API access
The following section describes the use cases of the capability and the Storefront API access scopes.
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.
Shopify handles the authentication for all API calls from an extension.
Anchor to Methods for accessing the Storefront APIMethods for accessing the Storefront API
Enabling the capability allows you to use the Standard API
query
method and the global fetch
to retrieve data from the Storefront API without manually managing token aquisition 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.
Both query
and fetch
will work for calling the Storefront API with the capability enabled. If you are using
fetch
to get data external to Shopify, refer to the capability
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
Enable Storefront API access
shopify.ui.extension.toml
examples
Enable Storefront API access
shopify.ui.extension.toml
type = "checkout_ui_extension" name = "my-checkout-extension" # ... [capabilities] api_access = true
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 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
Go to your Partner Dashboard.
Click the name of the app that you want to change.
Click App setup.
In the Checkout UI extensions section, on the Enable network access in checkout UI extensions card, click Request 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.
Add
network_access = true
to thesettings
section of your extension's configuration file.
Anchor to Required CORS headersRequired CORS headers
Since UI extensions run in a Web Worker, they have a null origin. They do not share the storefront or checkout's origin. For network calls to succeed, your server must support cross-origin resource sharing (CORS) for null origins by including this response header:
Access-Control-Allow-Origin: *
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 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.
Enable network access
shopify.ui.extension.toml
examples
Enable network access
shopify.ui.extension.toml
type = "checkout_ui_extension" name = "my-checkout-extension" # ... [capabilities] network_access = true
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.
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 capability.
Anchor to Granting the capability to block progressGranting the capability to block progress
Setting in the
shopify.ui.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.
When running a local extension with the capability, it will be automatically granted. This simulates a scenario where the merchant has allowed the capability.
Anchor to Detecting the ability to block progressDetecting the ability to block progress
In your extension, look for 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 capability from your
shopify.ui.extension.toml
file to simulate a merchant disallowing the capability.
We recommend having some UI to cover cases where you can't block checkout progress. For example, you might want to show a warning rather than block checkout progress when an order doesn't pass validation.
Enable progress blocking
shopify.ui.extension.toml
examples
Enable progress blocking
shopify.ui.extension.toml
type = "checkout_ui_extension" name = "my-checkout-extension" # ... [capabilities] block_progress = true
Anchor to settings-definitionSettings definition
The settings for a checkout UI extension define a set of fields that the merchant can set a value for from the checkout editor. You can use validation options to apply additional constraints to the data that the setting can store, such as a minimum or maximum value.
Each settings definition can include up to 20 settings.
All setting inputs are optional. You should code the extension so that it still works if the merchant hasn't set a value for the setting.
Anchor to PropertiesProperties
The following table describes the properties that you can use to define a setting:
Property | Required? | Description | Example |
---|---|---|---|
key | Yes | The key of the setting. When a merchant configures a value for this setting, the value will be exposed under this key when running your extension | "banner_title" |
type | Yes | The type of setting. | "single_line_text_field" |
name | Yes | The name of the setting. name is displayed to the merchant in the checkout editor. | "Banner title" |
description | No | The description of the setting. description is displayed to the merchant in the checkout editor. | "Enter a title for the banner." |
validations | No | Constraints on the setting input that Shopify validates. | validations: |
Anchor to Supported setting typesSupported setting types
The setting type determines the type of information that the setting can store. The setting types have built-in validation on the setting input.
Settings can have the following types:
Type | Description | Example value |
---|---|---|
boolean | A true or false value. | true |
date | A date in ISO 8601 format without a presumed time zone. | 2022-02-02 |
| A date and time in ISO 8601 format without a presumed time zone. | 2022-01-01T12:30:00 |
| A single line string. | Canada |
| A multi-line string. | Canada |
| A whole number in the range of +/-9,007,199,254,740,991. | 10 |
| A number with decimal places in the range of +/-9,999,999,999,999.999999999. | 10.4 |
| A globally-unique identifier (GID) for a product variant. | gid://shopify/ProductVariant/1 |
Anchor to Validation optionsValidation options
Each setting can include validation options. Validation options enable you to apply additional constraints to the data that a setting can store, such as a minimum or maximum value, or a regular expression. The setting's type
determines the available validation options.
You can include a validation option for a setting using the validation name
and a corresponding value
. The appropriate value depends on the setting type to which the validation applies.
The following table outlines the available validation options with supported types for applying constraints to a setting:
Validation option | Description | Supported types | Example |
---|---|---|---|
Minimum length | The minimum length of a text value. |
| [[settings.fields.validations]] |
Maximum length | The maximum length of a text value. |
| [[settings.fields.validations]] |
Regular expression | A regular expression. Shopify supports RE2. |
| [[settings.fields.validations]] |
Choices | A list of up to 128 predefined options that limits the values allowed for the metafield. |
| [[settings.fields.validations]] |
Minimum date | The minimum date in ISO 8601 format. | date | [[settings.fields.validations]] |
Maximum date | The maximum date in ISO 8601 format. | date | [[settings.fields.validations]] |
Minimum datetime | The minimum date and time in ISO 8601 format. |
| [[settings.fields.validations]] |
Maximum datetime | The maximum date and time in ISO 8601 format. |
| [[settings.fields.validations]] |
Minimum integer | The minimum integer number. |
| [[settings.fields.validations]] |
Maximum integer | The maximum integer number. |
| [[settings.fields.validations]] |
Minimum decimal | The minimum decimal number. |
| [[settings.fields.validations]] |
Maximum decimal | The maximum decimal number. |
| [[settings.fields.validations]] |
Maximum precision | The maximum number of decimal places to store for a decimal number. |
| [[settings.fields.validations]] |
Anchor to example-settings-definitionExample settings definition
The following example shows a settings definition that defines a setting named of type
. When the merchant sets a value for this setting from the checkout editor, Shopify validates that the provided value is between 5 and 20 characters in length
Learn more about the settings api by completing our custom banners example.
Example settings
shopify.ui.extension.toml
examples
Example settings
shopify.ui.extension.toml
[settings] [[settings.fields]] key = "banner_title" type = "single_line_text_field" name = "Banner title" description = "Enter a title for the banner." [[settings.fields.validations]] name = "min" value = "5" [[settings.fields.validations]] name = "max" value = "20"