Configuring 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.
How it works
Anchor link to section titled "How 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.
Extension types
Anchor link to section titled "Extension types"Some extensions require specific configurations. To accommodate this, Shopify CLI groups extensions into different types in the TOML file:
| Extension | type value in the TOML file |
--template flag value in the generate command |
|---|---|---|
| Checkout UI Developer preview |
ui_extension |
checkout_ui |
| Admin action | ui_extension |
admin_action |
| Admin block Developer preview |
ui_extension |
admin_block |
| Product configuration | ui_extension |
product_configuration |
| Shopify Flow trigger | flow_trigger |
flow_trigger |
| Shopify Flow action | flow_action |
flow_action |
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.
Supported targets
Anchor link to section titled "Supported targets"The following table provides links to documentation on the supported targets associated with each app extension:
| Extension | Documentation on supported targets |
|---|---|
| Checkout UI | Checkout UI target APIs |
| Admin UI | Admin UI target APIs |
| Product configuration | Add a product configuration extension |
| Shopify Flow trigger | Shopify Flow triggers |
| Shopify Flow action | Shopify Flow actions |
Common properties
Anchor link to section titled "Common 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 extensions.
| Property | Required? | Description |
|---|---|---|
api_version |
Yes | 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]] |
Yes | The name of the array that contains all extensions listed in the TOML file. |
name |
Yes | The merchant-facing name of the extension. After you generate an extension, you're prompted to provide a name for your extension. The name property is translatable if it starts with a t: and uses a key defined in your translation data. For example, you might have a t:name key that matches a translation key called name. Learn more about localization. Limitations:
|
description |
Yes | The merchant-facing description of the extension. The description property is translatable if it starts with a t: and uses a key defined in your translation data. For example, t:description and you have a matching translation key called description. Learn more about localization. |
handle |
Yes | The unique internal identifer for the extension. After you create a draft version of the extension, or deploy an extension, you can't change the handle value.If not specified, the handle value is automatically populated using a transformed name value that removes any unsupported characters. For example, if you enter google maps as the extension name, then Shopify populates the handle value as google-maps.Limitations:
|
type |
Yes | The extension type. For more information, refer to Extension types. |
[settings] |
No | 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]] |
No | The name of the array that contains the settings fields. Refer to Settings definition. |
[[extensions.targeting]] |
Yes | The name of the array that contains a target and path to the related extension code. |
target |
Yes | An identifier that specifies where you're injecting code into Shopify APIs, or other parts of the Shopify platform. For more information, refer to Targets. |
module |
Yes | The file that contains the extension code. |
Extension-specific properties
Anchor link to section titled "Extension-specific properties"This section describes the configuration settings in shopify.extension.toml that are specific to the following extensions:
- Checkout UI extensions
- Admin UI extensions
- Product configuration extensions
- Shopify Flow actions
- Shopify Flow triggers
Checkout UI extensions
Anchor link to section titled "Checkout UI extensions"The following example TOML file contains configuration settings for a checkout UI extension:
The following table describes the properties in the TOML file that are specific to checkout UI extensions:
| Property | Required? | Description |
|---|---|---|
[extensions.capabilities] |
No | The name of the array that contains the checkout UI extension's capabilities:
|
[extensions.metafields] |
No | An array that sets the default for each [[extensions.targeting.metafields]], if [[extensions.targeting.metafields]] isn't specified. |
[[extensions.targeting.metafields]] |
No | 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. |
Admin UI extensions
Anchor link to section titled "Admin 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:
Product configuration extensions
Anchor link to section titled "Product 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 Flow actions
Anchor link to section titled "Shopify Flow actions"The following example TOML file contains configuration settings for a Shopify Flow action:
The following table describes the properties in the TOML file that are specific to a Shopify Flow action:
| Property | Required? | Description |
|---|---|---|
runtime_url |
Yes | The endpoint where Flow sends your action's payload when your step is being executed at runtime. The payload contains data that you can use to execute the action in your app. |
validation_url |
No | An endpoint that validates the contents of custom properties in an action payload when an action is saved. This endpoint is only required if you want to use a custom configuration page. |
schema |
No | A relative path to a GraphQL schema definition file that contains custom types that you can use as part of your action. Only required if return_type_ref is also present. |
return_type_ref |
No | The name of the type to be returned by the action. This type must be present in the referenced schema file. Only required if schema is also present. |
config_page_url |
No | A route that renders your custom configuration page. |
config_page_preview_url |
No | An endpoint that provides data about your custom configuration page to display in the automation tool. This endpoint is only required if you want to use a custom configuration page. |
required in the [[settings.fields]] array |
Yes | Specifies whether a field is required (true) or optional (false). |
Shopify Flow triggers
Anchor link to section titled "Shopify 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:
Differences in TOML file names
Anchor link to section titled "Differences 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 - Shopify Functions:
shopify.function.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.