Configure app extensions

When you generate an app extension, Shopify CLI creates a TOML configuration file named shopify.extension.toml in the extension's directory. This file defines how Shopify builds, serves, and deploys your extension.

This page describes the configuration that's common across extension types. Each extension type also documents its own configuration properties — refer to Configuration for each extension type to find the reference for the type you're building.

Extension configuration is separate from app configuration. App-level settings, such as access scopes, authentication, webhook subscriptions, and app proxies, are defined in shopify.app.toml. For those settings, refer to App configuration.

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 Tables and nested propertiesTables and nested properties

A shopify.extension.toml file is organized into tables, where each table is a group of related key-value pairs. A table's header tells you two things:

Single table or array: Single brackets around a header (for example, [extensions.capabilities]) define a single table that appears once. Double brackets (like [[extensions]] or [[extensions.targeting]]) define an array of tables that can repeat, where each header of the same name adds another entry. A key with no header, like api_version = "2025-10", is top-level.
How properties are nested: A dotted header denotes a parent-child relationship. For example, [extensions.capabilities] is the capabilities table inside an extension. When the parent repeats, a nested table attaches to the most recent parent entry, so [[extensions.targeting.metafields]] belongs to [[extensions.targeting]] above it.

Indentation is optional and ignored by Shopify CLI. Generated files indent nested tables only for readability.

Anchor to Configuration for each extension typeConfiguration for each extension type

Each extension type documents its own configuration properties, along with an annotated example shopify.extension.toml. Use the following list to find the configuration reference for the extension type that you're building.

Anchor to Validation optionsValidation options

For some extension types, you can define fields in [[settings.fields]] that merchants use to configure your extension in the editor. Each of these settings can include validation options, which apply additional constraints to the value that the setting can store, such as a minimum or maximum value, or a regular expression. A setting's type determines the available validation options.

Include a validation option for a setting using the validation name and a corresponding value. The appropriate value depends on the setting type that the validation applies to.

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 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
App Home UI	`admin.app.home.render`
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 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?