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

ExpandOn this page

* [How it works](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#how-it-works)
* [Extension types](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#extension-types)
* [Targets](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#targets)
* [Common properties](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#common-properties)
* [Extension-specific properties](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#extension-specific-properties)
* [Differences in TOML file names](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#differences-in-toml-file-names)

# Configure app extensions

When you [generate an app extension](https://shopify.dev/docs/api/shopify-cli/app/app-generate-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:

* [Post-purchase UI](https://shopify.dev/docs/api/checkout-extensions/post-purchase/configuration)
* [Product subscription](https://shopify.dev/docs/apps/build/purchase-options/product-subscription-app-extensions/start-building)
* [Shopify Functions](https://shopify.dev/docs/api/functions/latest#configuration)
* [Theme app extensions](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/build)
* [Web pixel](https://shopify.dev/docs/apps/build/marketing-analytics/build-web-pixels)

***

## 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 = "2023-04"


[[extensions]]
name = "My UI extension"
description = "A UI extension"
handle = "my-ui-extension"
type = "ui_extension"


  [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"
```

***

## 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 |
| - | - | - |
| [Admin action](https://shopify.dev/docs/apps/build/admin/actions-blocks/build-admin-action) | `ui_extension` | `admin_action` |
| [Admin block](https://shopify.dev/docs/apps/build/admin/actions-blocks/build-admin-block) | `ui_extension` | `admin_block` |
| [Customer Account UI](https://shopify.dev/docs/api/customer-account-ui-extensions) | `ui_extension` | `customer_account_ui` |
| [Checkout UI](https://shopify.dev/docs/api/checkout-ui-extensions) | `ui_extension` | `checkout_ui` |
| [Editor extension collection](https://shopify.dev/docs/apps/build/customer-accounts/editor-extension-collections) developer preview | `editor_extension_collection` | `editor_extension_collection` |
| [Product configuration](https://shopify.dev/docs/apps/build/product-merchandising/bundles/product-configuration-extension/add-merchant-config-ui) | `ui_extension` | `product_configuration` |
| [Shopify Flow action](https://shopify.dev/docs/apps/build/flow/actions) | `flow_action` | `flow_action` |
| [Shopify Flow template](https://shopify.dev/docs/apps/build/flow/templates) | `flow_template` | `flow_template` |
| [Shopify Flow trigger](https://shopify.dev/docs/apps/build/flow/triggers) | `flow_trigger` | `flow_trigger` |
| [POS UI](https://shopify.dev/docs/api/pos-ui-extensions) | `ui_extension` | `pos_ui` |

Note

The `--template` flag value in the command to generate Shopify Functions extensions depends on the [Functions API](https://shopify.dev/docs/api/functions) that you're using.

***

## 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.

Note

Shopify Flow triggers and actions don't support configurable targets.

| Extension type | Documentation on supported targets |
| - | - |
| Admin UI | [Admin UI targets](https://shopify.dev/docs/api/admin-extensions/extension-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/extension-targets-overview) |
| 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. |

***

## Common properties

This section describes the configuration settings in `shopify.extension.toml` that are common to [Checkout UI](https://shopify.dev/docs/apps/build/checkout/technologies), [Admin UI](https://shopify.dev/docs/api/admin-extensions), [product configuration](https://shopify.dev/docs/apps/build/product-merchandising/bundles/product-configuration-extension/add-merchant-config-ui), [Shopify Flow triggers](https://shopify.dev/docs/apps/build/flow/triggers), [Shopify Flow actions](https://shopify.dev/docs/apps/build/flow/actions), and [Shopify Flow templates](https://shopify.dev/docs/apps/build/flow/templates) extensions.

Note

[POS UI extensions](https://shopify.dev/docs/api/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](https://shopify.dev/docs/api/shopify-cli/app/app-generate-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](https://shopify.dev/docs/apps/build/checkout/localized-checkout-ui-extensions#how-it-works). **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](https://shopify.dev/docs/apps/build/checkout/localized-checkout-ui-extensions#how-it-works).

- `handle`:required The unique internal identifier 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:**

  * Allowed characters: `a-z`, `A-Z`, `0-9`, `-`
  * 100 characters maximum
  * Must be unique within the app

- `type`:required The extension type. For more information, refer to [Extension types](#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](https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration#settings-definition). |
| `[[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](#targets).
- `module`:required The file that contains the extension code. |

***

## Extension-specific properties

This section describes the configuration settings in `shopify.extension.toml` that are specific to the following extensions:

* [Checkout UI extensions](#checkout-ui-extensions)
* [Customer Account UI extensions](#customer-account-ui-extensions)
* [Editor extension collection](#editor-extension-collection)
* [Admin UI extensions](#admin-ui-extensions)
* [Product configuration extensions](#product-configuration-extensions)
* [Shopify Flow actions](#shopify-flow-actions)
* [Shopify Flow triggers](#shopify-flow-triggers)
* [Shopify Flow templates](#shopify-flow-templates)

### Checkout UI extensions

The following example TOML file contains configuration settings for a [checkout UI extension](https://shopify.dev/docs/api/checkout-ui-extensions):

## shopify.extension.toml

```toml
api_version = "2023-04"


[[extensions]]
name = "My UI extension"
description = "A UI extension"
handle = "my-ui-extension"
type = "ui_extension"


  [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](https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration#api-access).
- `block_progress`:optional Whether your app extension can [block the customer's progress](https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration#block-progress).
- `network_access`:optional Whether your app extension can make [external network calls](https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration#network-access). |
| `[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](https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets/block/purchase-thank-you-block-render#standardapi-propertydetail-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). |

### Customer account UI extensions

The following example TOML files contain configuration settings for [a static and a full page extension](https://shopify.dev/docs/api/customer-account-ui-extensions/extension-targets-overview). The properties in the TOML files are similar to [checkout UI extensions](#checkout-ui-extensions):

## shopify.extension.toml

```toml
api_version = "2023-07"


[[extensions]]
type = "ui_extension"
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 checkout UI extension's capabilities:- `api_access`: Whether your app extension can [query the Storefront API](https://shopify.dev/docs/api/customer-account-ui-extensions/configuration#api-access).
- `network_access`: Whether your app extension can make [external network calls](https://shopify.dev/docs/api/customer-account-ui-extensions/configuration#network-access). |
| `[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](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/order-status/customer-account-order-status-block-render#orderstatusapi-propertydetail-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](https://shopify.dev/docs/apps/build/customer-accounts/extension-placement#define-default-placement) for the block extension target. |

### Editor extension collection

The following example TOML files contain configuration settings for an [editor extension collection](https://shopify.dev/docs/apps/build/customer-accounts/editor-extension-collections):

## shopify.extension.toml

```toml
[[extensions]]
name = "t:collection_name"
type = "editor_extension_collection"
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. |

### Admin UI extensions

The following example TOML files contain configuration settings for [an action and a block extension](https://shopify.dev/docs/apps/build/admin/actions-blocks). The properties in the TOML files are similar to [checkout UI extensions](#checkout-ui-extensions):

## shopify.extension.toml

```toml
api_version = "2023-04"


[[extensions]]
name = "My feature"
handle = "action-extension"
type = "ui_extension"


[[extensions.targeting]]
module = "actionExtension.jsx"
target = "admin.product.item.action.render"
```

## shopify.extension.toml

```toml
api_version = "2023-04"


[[extensions]]
name = "My block extension"
handle = "block-extension"
type = "ui_extension"


[[extensions.targeting]]
module = "blockExtension.jsx"
target = "admin.product.item.block.render"
```

### Product configuration extensions

The following example TOML file contains configuration settings for a [product configuration extension](https://shopify.dev/docs/apps/build/product-merchandising/bundles/product-configuration-extension/add-merchant-config-ui). The properties in the TOML file are similar to a [checkout UI extension](#checkout-ui-extensions):

## shopify.extension.toml

```toml
api_version = "2023-07"


[[extensions]]
name = "My product config extension"
handle = "my-product-config-extension"
type = "ui_extension"


[[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"
```

### Shopify Flow actions

The following example TOML file contains configuration settings for a [Shopify Flow action](https://shopify.dev/docs/apps/build/flow/actions):

## shopify.extension.toml

```toml
[[extensions]]
name = "Send email action"
description = "Send an email to a customer."
handle = "send-email-action"
type = "flow_action"
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 |
| - | - |
| `[[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](https://shopify.dev/docs/apps/build/flow/actions/endpoints#flow-action-execution) contains data that you can use to execute the action in your app.
- `validation_url`:optional [An endpoint](https://shopify.dev/docs/apps/build/flow/actions/endpoints#custom-validation) 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](https://shopify.dev/docs/apps/build/flow/actions/build-config-ui).
- `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](https://shopify.dev/docs/apps/build/flow/actions/build-config-ui).
- `config_page_preview_url`:optional [An endpoint](https://shopify.dev/docs/apps/build/flow/actions/endpoints#custom-configuration-page-preview) 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](https://shopify.dev/docs/apps/build/flow/actions/build-config-ui). |
| `[[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`). |

### Shopify Flow triggers

The following example TOML file contains configuration settings for a [Shopify Flow trigger](https://shopify.dev/docs/apps/build/flow/triggers). The properties in the TOML file are similar to a [Shopify Flow action](#shopify-flow-actions):

## shopify.extension.toml

```toml
[[extensions]]
name = "Shopify Email sent"
description = "Triggered when an email is sent from Shopify"
handle = "shopify-email-sent"
type = "flow_trigger"


[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"
```

### Shopify Flow templates

The following example TOML file contains configuration settings for a [Shopify Flow template](https://shopify.dev/docs/apps/build/flow/templates).

## shopify.extension.toml

```toml
[[extensions]]
name = "t:name"
type = "flow_template"
handle = "example-name"
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 |
| - | - |
| `[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. |

***

## 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`.

***

* [How it works](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#how-it-works)
* [Extension types](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#extension-types)
* [Targets](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#targets)
* [Common properties](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#common-properties)
* [Extension-specific properties](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#extension-specific-properties)
* [Differences in TOML file names](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#differences-in-toml-file-names)