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.

Some extension types use different TOML structures and are documented in other 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

api_version = "2025-10"

[[extensions]]

name = "My UI extension"

description = "A UI extension"

handle = "my-ui-extension"

type = "ui_extension"

uid = "1aafc25d-8448-218e-9373-b3d91ac2a0af75f73e12"

[extensions.capabilities]

api_access = true

block_progress = true

network_access = true

[[extensions.targeting]]

module = "./src/CheckoutDynamicRender.js"

target = "purchase.checkout.block.render"

[[extensions.targeting.metafields]]

key = "my-key"

namespace = "my-namespace"

[settings]

[[settings.fields]]

key = "banner_title"

type = "single_line_text_field"

name = "Banner title"

description = "Enter a title for the banner"

Anchor to Extension typesExtension 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
Admin action	`ui_extension`	`admin_action`
Admin block	`ui_extension`	`admin_block`
Customer Account UI	`ui_extension`	`customer_account_ui`
Checkout UI	`ui_extension`	`checkout_ui`
Editor extension collection	`editor_extension_collection`	`editor_extension_collection`
Product configuration	`ui_extension`	`product_configuration`
Shopify Flow action	`flow_action`	`flow_action`
Shopify Flow template	`flow_template`	`flow_template`
Shopify Flow trigger	`flow_trigger`	`flow_trigger`
POS UI	`ui_extension`	`pos_ui`
Functions	`function`	Varies by Functions API

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.

Extension type	Documentation on supported targets
Admin UI	Admin UI targets
Checkout UI	Checkout UI targets
Customer Account UI	Customer Account UI targets
POS UI	POS UI targets
Product configuration	Product configuration app extensions use the admin.product-details.configuration.render or admin.product-variant-details.configuration.render target.
Functions	Functions targets

Anchor to Common propertiesCommon properties

This section describes the configuration settings in shopify.extension.toml that are common to Checkout UI, Admin UI, product configuration, Shopify Flow triggers, Shopify Flow actions, and Shopify Flow templates extensions.

Note

POS UI extensions only support the required properties listed in the table.

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: `name`:required 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: Supports any characters. Shopify Flow actions and Shopify Flow triggers extensions can only include alphanumeric characters and spaces. 5 characters minimum 30 characters maximum `description`:required 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`:required A unique reference name for the extension. Used when referencing the extension in configuration, APIs, and the Dev Dashboard. Limitations: Allowed characters: `a-z`, `A-Z`, `0-9`, `-` 100 characters maximum Must be unique within the app `uid`:required The extension user identifier. An app-scoped identifier used by `shopify app deploy` to determine whether an extension is being created, updated, or deleted. Limitations: Must be unique within the app `type`:required The extension type. For more information, refer to Extension types.
`[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: `target`:required 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`:required The file that contains the extension code.

Anchor to Settings fieldsSettings fields

Settings let merchants customize your extension from the editor. All setting inputs are optional unless marked as required — code your extension so it still works if the merchant hasn't set a value.

Each field in [[settings.fields]] accepts the following properties:

key: The identifier for the setting. The configured value is exposed under this key at runtime.
type: The setting type. Determines what input the merchant sees and how the value is validated.
name: The merchant-facing display name for the setting.
description: Help text displayed to the merchant in the editor.
validations: Constraints on the input. See validation options.

Anchor to Supported setting typesSupported setting types

The following setting types apply to checkout UI extensions and customer account UI extensions. Other extension types may support additional 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.

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`
`date_time`	A date and time in ISO 8601 format without a presumed time zone.	`2022-01-01T12:30:00`
`single_line_text_field`	A single line string.	`Canada`
`multi_line_text_field`	A multi-line string.	`Canada`
`number_integer`	A whole number in the range of +/-9,007,199,254,740,991.	`10`
`number_decimal`	A number with decimal places in the range of +/-9,999,999,999,999.999999999.	`10.4`
`variant_reference`	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.

Validation option	Description	Supported types	Example
Minimum length	The minimum length of a text value.	`single_line_text_field`, `multi_line_text_field`	`name = "min"` `value = "8"`
Maximum length	The maximum length of a text value.	`single_line_text_field`, `multi_line_text_field`	`name = "max"` `value = "25"`
Regular expression	A regular expression. Shopify supports RE2.	`single_line_text_field`, `multi_line_text_field`	`name = "regex"` `value = "(@)(.+)$"`
Choices	A list of up to 128 predefined options that limits the values allowed for the setting.	`single_line_text_field`	`name = "choices"` `value = '["red", "green", "blue"]'`
Minimum date	The minimum date in ISO 8601 format.	`date`	`name = "min"` `value = "2022-01-01"`
Maximum date	The maximum date in ISO 8601 format.	`date`	`name = "max"` `value = "2022-03-03"`
Minimum datetime	The minimum date and time in ISO 8601 format.	`date_time`	`name = "min"` `value = "2022-01-01T00:00:00"`
Maximum datetime	The maximum date and time in ISO 8601 format.	`date_time`	`name = "max"` `value = "2022-03-03T00:00:00"`
Minimum integer	The minimum value of an integer.	`number_integer`	`name = "min"` `value = "0"`
Maximum integer	The maximum value of an integer.	`number_integer`	`name = "max"` `value = "100"`
Minimum decimal	The minimum value of a decimal number.	`number_decimal`	`name = "min"` `value = "0.5"`
Maximum decimal	The maximum value of a decimal number.	`number_decimal`	`name = "max"` `value = "99.99"`
Maximum precision	The maximum number of decimal places to store for a decimal number.	`number_decimal`	`name = "max_precision"` `value = "2"`

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
POS 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

api_version = "2025-10"

[[extensions]]

name = "My UI extension"

description = "A UI extension"

handle = "my-ui-extension"

type = "ui_extension"

uid = "1aafc25d-8448-218e-9373-b3d91ac2a0af75f73e12"

[extensions.capabilities]

api_access = true

block_progress = true

network_access = true

[[extensions.targeting]]

module = "./src/CheckoutDynamicRender.js"

target = "purchase.checkout.block.render"

default_placement = "WALLETS1"

[[extensions.targeting.metafields]]

key = "my-key"

namespace = "my-namespace"

[settings]

[[settings.fields]]

key = "banner_title"

type = "single_line_text_field"

name = "Banner title"

description = "Enter a title for the banner"

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: `api_access`:optional Whether your app extension can query the Storefront API. `block_progress`:optional Whether your app extension can block the customer's progress. `network_access`:optional Whether your app extension can make external network calls. `collect_buyer_consent`:optional Whether your app extension can collect buyer consent for SMS marketing (`sms_marketing`) or customer privacy (`customer_privacy`).
`[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`:optional The name for the metafield. `namespace`:optional A container for a group of metafields. Grouping metafields within a namespace prevents your metafields from conflicting with other metafields with the same key name. You can specify up to five `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

api_version = "2025-10"

[[extensions]]

type = "ui_extension"

uid = "9ebaa5f0-a0d8-25bf-6290-c55f579e4dfac7c7fcd2"

name = "customer-account-ui"

handle = "customer-account-ui"

[[extensions.targeting]]

module = "./src/CustomerAccountOrderIndexExtension.tsx"

target = "customer-account.order-index.block.render"

default_placement = "ORDER_INDEX"

[[extensions.targeting]]

module = "./src/CustomerAccountExtensionFullPage.tsx"

target = "customer-account.page.render"

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 customer account UI extension's capabilities: `api_access`: Whether your app extension can query the Storefront API. `network_access`: Whether your app extension can make external network calls. Before requesting network access, consider whether metafields can provide the data your extension needs. `collect_buyer_consent`: Whether your app extension can collect buyer consent for SMS marketing (`sms_marketing`) or customer privacy (`customer_privacy`).
`[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`: The name for the metafield. `namespace`: A container for a group of metafields. Grouping metafields within a namespace prevents your metafields from conflicting with other metafields with the same key name. You can specify up to five `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 Supported resource metafield typesSupported resource metafield types

Supported resource metafield types for customer account UI extensions include:

Resource	Description
`cart`	The cart associated with the checkout.
`customer`	The customer associated with the order.
`order`	The order being viewed.
`company`	The company for B2B orders.
`companyLocation`	The company's location for B2B orders.
`product`	The products in the order.
`shop`	The shop associated with the order.
`variant`	The product variants in the order.

Anchor to App-owned metafieldsApp-owned metafields

App-owned metafields are supported. You can use app-owned metafields when your app needs to control the data and visibility of the metafield.

Your extension can access app-owned metafields that are requested in its TOML using the $app format. Your extension can only access app-owned metafields that belong to its parent app.

Caution

When accessing app-owned metafields, you must use the $app format. The fully qualified reserved namespace format such as app--{your-app-id}[--{optional-namespace}] is not supported.

Anchor to POS UI extensionsPOS UI extensions

The following example TOML file contains configuration settings for a POS UI extension configured to run offline:

shopify.extension.toml

api_version = "2026-01"

[[extensions]]

name = "My POS UI extension"

description = "A POS UI extension"

handle = "my-pos-ui-extension"

type = "ui_extension"

uid = "1aafc25d-8448-218e-9373-b3d91ac2a0af75f73e12"

[extensions.supported_features]

runs_offline = true

[[extensions.targeting]]

target = "pos.home.tile.render"

module = "./src/Tile.tsx"

[[extensions.targeting]]

target = "pos.home.modal.render"

module = "./src/Modal.tsx"

The following table describes the properties in the TOML file that are specific to POS UI extensions:

Property	Description
`[extensions.supported_features]` optional	Declares additional features for your extension. Contains the following property: `runs_offline`:optional When set to `true`, the extension runs even when POS is offline. Defaults to `false`. When your extension runs offline, it continues to function using locally available data and APIs that don't require network connectivity. For more information, refer to Run extensions offline.

Anchor to Editor extension collectionEditor extension collection

The following example TOML files contain configuration settings for an editor extension collection:

shopify.extension.toml

[[extensions]]

name = "t:collection_name"

type = "editor_extension_collection"

uid = "8723da04-b91d-e812-2091-52c161b3b2892fa89479"

handle = "editor-extension-collection"

includes=["customer-account-ui", "checkout-ui-extension"]

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: Currently, can only contain customer account UI and checkout UI extensions. Must contain two or more extensions.

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

api_version = "2025-10"

[[extensions]]

name = "My feature"

handle = "action-extension"

type = "ui_extension"

uid = "3e9ce641-7624-b901-fdef-cc194f77a8720c5af6e5"

[[extensions.targeting]]

module = "actionExtension.jsx"

target = "admin.product.item.action.render"

shopify.extension.toml

api_version = "2025-10"

[[extensions]]

name = "My block extension"

handle = "block-extension"

type = "ui_extension"

uid = "f62f100d-15e6-9866-eda9-23f99de4b5d26e347042"

[[extensions.targeting]]

module = "blockExtension.jsx"

target = "admin.product.item.block.render"

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

api_version = "2025-10"

[[extensions]]

name = "My product config extension"

handle = "my-product-config-extension"

type = "ui_extension"

uid = "8a8e0c98-1efb-7556-dfbb-04bdcfea1662b066ab00"

[[extensions.targeting]]

module = "./src/ProductDetailsConfigurationExtension.tsx"

target = "admin.product-details.configuration.render"

[[extensions.targeting]]

module = "./src/ProductVariantDetailsConfigurationExtension.tsx"

target = "admin.product-variant-details.configuration.render"

Anchor to Shopify Flow actionsShopify Flow actions

The following example TOML file contains configuration settings for a Shopify Flow action:

shopify.extension.toml

[[extensions]]

name = "Send email action"

description = "Send an email to a customer."

handle = "send-email-action"

type = "flow_action"

uid = "e75268dd-a0bf-45f9-2c95-b988a06f307920b6602c"

runtime_url = "https://runtime-endpoint.com"

schema = "./schema.graphql"

return_type_ref = "EmailDelivered"

validation_url = "https://validation-url"

config_page_url = "https://url.com/config"

config_page_preview_url = "https://url.com/config/preview"

[settings]

[[settings.fields]]

description = "The email address to send to"

key = "email_address"

name = "Email address"

type = "single_line_text_field"

required = true

[[settings.fields]]

description = "The subject of the email"

key = "subject"

name = "Subject"

type = "single_line_text_field"

required = true

[[settings.fields]]

description = "The body of the email"

key = "body"

name = "Body"

type = "multi_line_text_field"

required = true

The following table describes the properties in the TOML file that are specific to a Shopify Flow action:

Property Description

Property	Description
`[[extensions]]` required	The name of the array that contains all extensions listed in the TOML file. Contains the following properties: `runtime_url`:required 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`:optional 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`:optional 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`:optional 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`:optional A route that renders your custom configuration page. `config_page_preview_url`:optional 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.
`[[settings.fields]]` required	The name of the array that contains the settings fields. Contains the following property: `required`:required Specifies whether a field is required (`true`) or optional (`false`).

[[extensions]]
required

The name of the array that contains all extensions listed in the TOML file. Contains the following properties:

runtime_url:required 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:optional 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:optional 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:optional 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:optional A route that renders your custom configuration page.
config_page_preview_url:optional 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.

[[settings.fields]]
required

The name of the array that contains the settings fields. Contains the following property:

required:required Specifies whether a field is required (true) or optional (false).

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

[[extensions]]

name = "Shopify Email sent"

description = "Triggered when an email is sent from Shopify"

handle = "shopify-email-sent"

type = "flow_trigger"

uid = "1b625187-49cd-77d4-524b-5cfbb4582529885aa0fe"

[settings]

[[settings.fields]]

description = "The customer who received the email."

key = "customer_id"

name = "Customer ID"

type = "customer_reference"

[[settings.fields]]

description = "The marketing campaign ID."

key = "campaign_id"

name = "Campaign ID"

type = "single_line_text_field"

Anchor to Shopify Flow templatesShopify Flow templates

The following example TOML file contains configuration settings for a Shopify Flow template.

shopify.extension.toml

[[extensions]]

name = "t:name"

type = "flow_template"

uid = "7fec5c80-7dd4-5fbc-1eb5-203e4bd8e1bfe9ec810a"

handle = "example-handle"

description = "t:description"

[extensions.template]

categories = ["orders", "risk"]

module = "./template.flow"

require_app = false

discoverable = true

enabled = true

The following table describes the properties in the TOML file that are specific to a Shopify Flow template:

Property Description

Property	Description
`[extensions.template]` required	Settings related to the template. Contains the following properties: `categories`:required The categories that best describe the function of your template. Must be an array containing only strings of valid categories. Must choose at least one category. Max 2 recommended. Valid categories are: `buyer_experience`, `customers`, `inventory_and_merch`, `loyalty`, `orders`, `promotions`, `risk`, `fulfillment`, `b2b`, `payment_reminders`, `custom_data`, and `error_monitoring`. `module`:required The file path of the template workflow in the extension's folder. `require_app`:optional Whether your template is visible only to merchants who have your app installed. Defaults to `false` if not provided. `discoverable`:optional Whether your template should be displayed in the template browser. When `false`, the template is accessible only through a deep link. Defaults to `true` if not provided. `enabled`:optional Whether your template should be made available after being approved and released. Defaults to `true` if not provided.

[extensions.template]
required

Settings related to the template. Contains the following properties:

categories:required The categories that best describe the function of your template. Must be an array containing only strings of valid categories. Must choose at least one category. Max 2 recommended. Valid categories are: buyer_experience, customers, inventory_and_merch, loyalty, orders, promotions, risk, fulfillment, b2b, payment_reminders, custom_data, and error_monitoring.
module:required The file path of the template workflow in the extension's folder.
require_app:optional Whether your template is visible only to merchants who have your app installed. Defaults to false if not provided.
discoverable:optional Whether your template should be displayed in the template browser. When false, the template is accessible only through a deep link. Defaults to true if not provided.
enabled:optional Whether your template should be made available after being approved and released. Defaults to true if not provided.

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
If you generated an extension after July 26, 2023, then the TOML file is named shopify.extension.toml.

Was this page helpful?