Configure app extensions
When you generate an app extension, a TOML configuration file named shopify.extension.toml
is automatically generated in your app's extension directory.
This guide describes the TOML file structure that only applies to checkout UI, admin UI, customer account UI, product configuration, Shopify Flow triggers, Shopify Flow actions, and Shopify Flow templates extensions. The TOML file structure for other extensions is described in the following topics:
Anchor to How it worksHow it works
Shopify CLI builds and serves app extensions using information defined in a TOML file named shopify.extension.toml
. The TOML file is located in a directory within the extensions/
directory of your app project.
The following example shows a shopify.extension.toml
file that contains configuration settings for a checkout UI extension.
shopify.extension.toml
Anchor to Extension typesExtension types
Some extensions require specific configurations. To accommodate this, Shopify CLI groups extensions into different types in the TOML file:
The --template
flag value in the command to generate Shopify Functions extensions depends on the Functions API that you're using.
Anchor to TargetsTargets
A target is an identifier in shopify.extension.toml
that specifies where you're injecting code into Shopify APIs, or other parts of the Shopify platform.
Each target is composed of three to four namespaces. The name begins with a broad Shopify context and ends with the behavior of the extensible element. For example, a checkout UI extension that renders a shipping address form has a target named purchase.checkout.delivery-address.render-before
:
purchase
: The broad Shopify context.checkout
: The targeted page.delivery-address
: The element that the extension will be positioned near.render-before
: An action verb that describes the behavior of the extensible element.
Anchor to Supported targetsSupported targets
The following table provides links to documentation on the supported targets associated with each app extension type.
Shopify Flow triggers and actions don't support configurable targets.
Extension type | Documentation on supported targets |
---|---|
Checkout UI | Checkout UI targets |
Customer account UI | Customer Account UI targets |
Admin UI | Admin UI targets |
Product configuration | Product configuration app extensions use the admin.product-details.configuration.render or admin.product-variant-details.configuration.render target. |
Anchor to Common propertiesCommon properties
This section describes the configuration settings in shopify.extension.toml
that are common to checkout UI extensions, admin UI, product configuration, Shopify Flow triggers, Shopify Flow actions, and Shopify Flow templates extensions.
Property | Description |
---|---|
api_version required | The version of the API that's being used for the extension. If provided in the [[extensions]] array, then the specified API version is used instead of the root level api_version . |
[[extensions]] required | The name of the array that contains all extensions listed in the TOML file. Contains the following properties:
|
[settings] optional | The name of the array that defines settings that a merchant can set values for. If provided in the [[extensions]] array, then the specified settings are used instead of the root level settings . |
[[settings.fields]] optional | The name of the array that contains the settings fields. |
[[extensions.targeting]] required | The name of the array that contains a target and path to the related extension code. Contains the following required properties:
|
Anchor to Extension-specific propertiesExtension-specific properties
This section describes the configuration settings in shopify.extension.toml
that are specific to the following extensions:
- Checkout UI extensions
- Customer account UI extensions
- Editor extension collection
- Admin UI extensions
- Product configuration extensions
- Shopify Flow actions
- Shopify Flow triggers
- Shopify Flow templates
Anchor to Checkout UI extensionsCheckout UI extensions
The following example TOML file contains configuration settings for a checkout UI extension:
shopify.extension.toml
The following table describes the properties in the TOML file that are specific to checkout UI extensions:
Property | Description |
---|---|
[extensions.capabilities] optional | The name of the array that contains the checkout UI extension's capabilities:
|
[extensions.metafields] optional | An array that sets the default for each [[extensions.targeting.metafields]] , if [[extensions.targeting.metafields]] isn't specified. |
[[extensions.targeting.metafields]] optional | The metafields that your extension target needs to read:
key and namespace pairs in the configuration file. When the extension is executed, Shopify looks for the metafields in each resource and returns their contents. |
[[extensions.targeting.default_placement]] optional | Defines which location of a block extension target an extension is placed in when added. After adding the extension, the merchant can move it to other locations. Value must be a checkout [block extension target](/docs/apps/build/checkout/test-checkout-ui-extensions#block-extension targets). |
Anchor to Customer account UI extensionsCustomer account UI extensions
The following example TOML files contain configuration settings for a static and a full page extension. The properties in the TOML files are similar to checkout UI extensions:
shopify.extension.toml
The following table describes the properties in the TOML file that are specific to customer account UI extensions:
Property | Description |
---|---|
[extensions.capabilities] optional | The name of the array that contains the checkout UI extension's capabilities:
|
[extensions.metafields] optional | An array that sets the default for each [[extensions.targeting.metafields]] , if [[extensions.targeting.metafields]] isn't specified. |
[[extensions.targeting.metafields]] optional | The metafields that your extension target needs to read:
key and namespace pairs in the configuration file. When the extension is executed, Shopify looks for the metafields in each resource and returns their contents. |
[[extensions.targeting.default_placement]] optional | Defines which location of a block extension target an extension is placed in when added. After adding the extension, the merchant can move it to other locations. Value must be one of the customer account placements for the block extension target. |
Anchor to Editor extension collectionEditor extension collection
The following example TOML files contain configuration settings for an editor extension collection:
shopify.extension.toml
The following table describes the properties in the TOML file that are specific to editor extension collections:
Property | Required? | Description |
---|---|---|
[extensions.includes] | Yes | An array that sets the supported extensions that belong in the editor extension collection. Limitations:
|
Anchor to Admin UI extensionsAdmin UI extensions
The following example TOML files contain configuration settings for an action and a block extension. The properties in the TOML files are similar to checkout UI extensions:
shopify.extension.toml
shopify.extension.toml
Anchor to Product configuration extensionsProduct configuration extensions
The following example TOML file contains configuration settings for a product configuration extension. The properties in the TOML file are similar to a checkout UI extension:
shopify.extension.toml
Anchor to Shopify Flow actionsShopify Flow actions
The following example TOML file contains configuration settings for a Shopify Flow action:
shopify.extension.toml
The following table describes the properties in the TOML file that are specific to a Shopify Flow action:
Property | Description |
---|---|
[[extensions]] required | The name of the array that contains all extensions listed in the TOML file. Contains the following properties:
|
[[settings.fields]] required | The name of the array that contains the settings fields. Contains the following property:
|
Anchor to Shopify Flow triggersShopify Flow triggers
The following example TOML file contains configuration settings for a Shopify Flow trigger. The properties in the TOML file are similar to a Shopify Flow action:
shopify.extension.toml
Anchor to Shopify Flow templatesShopify Flow templates
The following example TOML file contains configuration settings for a Shopify Flow template.
shopify.extension.toml
The following table describes the properties in the TOML file that are specific to a Shopify Flow template:
Property | Description |
---|---|
[extensions.template] required | Settings related to the template. Contains the following properties:
|
Anchor to Differences in TOML file namesDifferences in TOML file names
TOML file names can differ, depending on when you generated an extension:
-
If you generated an extension before July 26, 2023, then your TOML file maps to one of the following names:
- Checkout UI:
shopify.ui.extension.toml
- Bundles UI extension:
shopify.ui.extension.toml
(maps to a product configuration extension) - Post-purchase UI:
shopify.ui.extension.toml
- Product subscription:
shopify.ui.extension.toml
- Web pixel:
shopify.ui.extension.toml
- Shopify POS UI:
shopify.ui.extension.toml
- Theme app extensions:
shopify.theme.extension.toml
- Checkout UI:
-
If you generated an extension after July 26, 2023, then the TOML file is named
shopify.extension.toml
.