• How it works
  • Extension types
  • Targets
  • Common properties
  • Extension-specific properties
  • Differences in TOML file names

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.

Note

This guide describes the TOML file structure that only applies to checkout UI, admin UI, customer account UI, product configuration, Shopify Flow triggers, Shopify Flow actions, Shopify Flow templates, and Shopify Functions extensions.

The TOML file structure for other extensions follow a different pattern:

  • Post-purchase UI
  • Product subscription
  • Web pixel
  • Shopify POS UI
  • Theme app extensions

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 ui_extension checkout_ui
Customer account UI
Developer preview		 ui_extension customer_account_ui
Editor extension collection
Developer preview		 editor_extension_collection editor_extension_collection
Admin action ui_extension admin_action
Admin block ui_extension admin_block
Product configuration ui_extension product_configuration
Shopify Flow trigger flow_trigger flow_trigger
Shopify Flow action flow_action flow_action
Shopify Flow template flow_template flow_template
Order discount function order_discounts
Product discount function product_discounts
Shipping discount
Developer preview		 function shipping_discounts
Discounts allocator
Developer preview		 function discounts_allocator
Delivery customization function delivery_customization
Payment customization function payment_customization
Order routing location rule
Beta		 function order_routing_location_rule
Cart and checkout validation function cart_checkout_validation
Cart transform function cart_transform
Fulfillment constraints function fulfillment_constraints

Targets

Anchor link to section titled "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

Anchor link to section titled "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
Checkout UI Checkout UI targets
Customer account UI Customer Account UI targets
Admin UI Admin UI targets
Product configuration Product configuration app extensions use the admin.product-details.configuration.render or admin.product-variant-details.configuration.render target.
Shopify Functions Shopify function APIs and targets

The available targets depend on the Function APIs that you're using.

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, Shopify Flow templates, and Shopify Functions extensions.

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

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
  • Customer account UI extensions
  • Editor extension collection
  • Admin UI extensions
  • Product configuration extensions
  • Shopify Flow actions
  • Shopify Flow triggers
  • Shopify Flow templates
  • Shopify Functions extensions

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 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.
[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 one of the checkout placements for the block extension target.

Customer account UI extensions

Anchor link to section titled "Customer 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:

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.
  • network_access: Whether your app extension can make external network calls.
[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.

Editor extension collection

Anchor link to section titled "Editor extension collection"

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

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

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

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:

Shopify Flow templates

Anchor link to section titled "Shopify Flow templates"

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

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.

Shopify Functions extensions

Anchor link to section titled "Shopify Functions extensions"

The following example TOML file contains configuration settings for a Shopify Function extension:

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

Property Description
[[extensions.targeting]]
Required		 The name of the array that contains a target and its associated WebAssembly module export. Contains the following properties:

  • target:Required An identifier that specifies where you're injecting code into the Shopify backend. Refer to the Function API references for available function targets.
  • input_query:Optional The path to the input query file for the target. If omitted, then the function receives no input.
  • export:Optional The name of the WebAssembly export in your module that executes for the target. Functions don't use the extensions.targeting.module setting. Use export instead. Defaults to _start.
[extensions.build]
Optional		 The settings related to the build and deployment of the function extension's WebAssembly module. Contains the following properties:

  • command:Optional The command to build the function, which is invoked by the Shopify CLI build command.
  • path:Optional The relative path to the function's WebAssembly module. For example, build/my-module.wasm. Defaults to dist/index.wasm.
  • watch:Optional The relative paths that Shopify CLI should watch when the dev command is invoked. Changes to matched files trigger a build of the function and update it in your application drafts. This setting accepts a single file path or glob pattern, or an array of file paths and glob patterns.

    For JavaScript and TypeScript functions, this setting defaults to ['src/**/*.js', 'src/**/*.ts'].

    Input queries are automatically included in watch paths and don't need to be configured in build.watch.
[extensions.ui]
Optional		 The settings related to the merchant interface for your function. Contains the following properties:

  • handle: Optional Learn how to create your function merchant interface.
  • enable_create:Optional Learn how to configure creation workflows for function owners.
[extensions.ui.paths]
Optional		 The settings related to the App Bridge paths of the merchant interface for your function. Contains the following properties:

  • create:Optional Refer to create your function merchant interface.
  • details:Optional Refer to create your function merchant interface.
[extensions.input.variables]
Optional		 The variables to use in your input query. Contains the following properties:

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

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

  • If you generated an extension after July 26, 2023, then the TOML file is named shopify.extension.toml.

On this page

  • How it works
  • Extension types
  • Targets
  • Common properties
  • Extension-specific properties
  • Differences in TOML file names