--- title: Configure app extensions description: Learn about app extension properties that you can configure in the TOML file. source_url: html: 'https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions' md: >- https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions.md --- # Configure app extensions When you [generate an app extension](https://shopify.dev/docs/api/shopify-cli/app/app-generate-extension), [Shopify CLI](https://shopify.dev/docs/apps/build/cli-for-apps) 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](#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](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration). *** ## How it works [Shopify CLI](https://shopify.dev/docs/apps/build/cli-for-apps) 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](https://shopify.dev/docs/apps/build/cli-for-apps/app-structure#directory-structure) of your app project. The following example shows a `shopify.extension.toml` file that contains configuration settings for a [checkout UI extension](https://shopify.dev/docs/api/checkout-ui-extensions). ## shopify.extension.toml ```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" ``` ### Tables 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. *** ## Configuration 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. * [Admin link](https://shopify.dev/docs/apps/build/admin/admin-links/create-admin-links) * [Admin UI](https://shopify.dev/docs/api/admin-extensions/latest#configuration) * [App Home UI](https://shopify.dev/docs/api/app-home-ui-extension/latest#configuration) * [Checkout UI](https://shopify.dev/docs/api/checkout-ui-extensions/latest#configuration) * [Customer account UI](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#configuration) * [Editor extension collection](https://shopify.dev/docs/apps/build/customer-accounts/editor-extension-collections/configuration) * [Events subscription](https://shopify.dev/docs/api/events/latest#configuration) * [Payments](https://shopify.dev/docs/apps/build/payments/configuration) * [POS UI](https://shopify.dev/docs/api/pos-ui-extensions/latest#configuration) * [Post-purchase UI](https://shopify.dev/docs/api/checkout-extensions/post-purchase/configuration) * [Product configuration](https://shopify.dev/docs/api/admin-extensions/latest#configuration) * [Shopify Flow action](https://shopify.dev/docs/apps/build/flow/actions/reference) * [Shopify Flow template](https://shopify.dev/docs/apps/build/flow/templates/reference) * [Shopify Flow trigger](https://shopify.dev/docs/apps/build/flow/triggers/reference) * [Shopify Flow trigger lifecycle callback](https://shopify.dev/docs/apps/build/flow/track-lifecycle-events#configuration) * [Shopify Functions](https://shopify.dev/docs/api/functions/latest#configuration) * [Subscription link](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/subscription-link-extensions/start-building#step-1-generate-a-new-extension) * [Theme app extension](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration#configuration-file) * [Web pixel](https://shopify.dev/docs/apps/build/marketing/build-web-pixels) * [Webhook subscription](https://shopify.dev/docs/apps/build/webhooks/subscribe#app-specific-subscriptions) *** ## Validation 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](https://github.com/google/re2/wiki/Syntax). | `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](https://www.iso.org/iso-8601-date-and-time-format.html) format. | `date` | `name = "min"` `value = "2022-01-01"` | | Maximum date | The maximum date in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. | `date` | `name = "max"` `value = "2022-03-03"` | | Minimum datetime | The minimum date and time in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. | `date_time` | `name = "min"` `value = "2022-01-01T00:00:00"` | | Maximum datetime | The maximum date and time in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) 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"` | *** ## Targets 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 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](https://shopify.dev/docs/api/admin-extensions/extension-targets) | | App Home UI | [`admin.app.home.render`](https://shopify.dev/docs/api/app-home-ui-extension/latest/targets) | | Checkout UI | [Checkout UI targets](https://shopify.dev/docs/api/checkout-ui-extensions/current/targets) | | Customer Account UI | [Customer Account UI targets](https://shopify.dev/docs/api/customer-account-ui-extensions/targets) | | POS UI | [POS UI targets](https://shopify.dev/docs/api/pos-ui-extensions/targets) | | Product configuration | Product configuration app extensions use the [admin.product-details.configuration.render](https://shopify.dev/docs/api/admin-extensions/extension-targets#extensiontargets-propertydetail-adminproductdetailsconfigurationrender) or [admin.product-variant-details.configuration.render](https://shopify.dev/docs/api/admin-extensions/extension-targets#extensiontargets-propertydetail-adminproductvariantdetailsconfigurationrender) target. | | Functions | [Functions targets](https://shopify.dev/docs/api/functions/latest#function-extension-target-types) | *** ## 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](https://shopify.dev/docs/apps/build/product-merchandising/bundles/product-configuration-extension/add-merchant-config-ui)) * **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`. ***