When you create a [checkout UI extension](/api/checkout-ui-extensions/), an [app extension configuration](/docs/apps/app-extensions/configuration) `shopify.extension.toml` file is automatically generated in your extension's directory. This guide describes [extension targeting](#targets), [capabilities](#capabilities), [metafields](#metafields), and the [settings](#settings-definition) you can configure in the app extension configuration.
You define properties for your checkout UI extension in the extension configuration file. The `shopify.extension.toml` file contains the extension's configuration, which includes the extension name, targets, metafields, capabilities, and settings. When an extension is published to Shopify, the contents of the settings file are pushed alongside the extension.
api_version = "2023-07"
[[extensions]]
type = "ui_extension"
name = "My checkout extension"
handle = "checkout-ui"
[[extensions.targeting]]
target = "purchase.checkout.block.render"
module = "./Checkout.jsx"
[extensions.capabilities]
network_access = true
block_progress = true
api_access = true
[extensions.capabilities.collect_buyer_consent]
sms_marketing = true
customer_privacy = true
[[extensions.metafields]]
namespace = "my-namespace"
key = "my-key"
[[extensions.metafields]]
namespace = "my-namespace"
key = "my-other-key"
[extensions.settings]
[[extensions.settings.fields]]
key = "field_key"
type = "boolean"
name = "field-name"
[[extensions.settings.fields]]
key = "field_key_2"
type = "number_integer"
name = "field-name-2"
Your code should have a default export if it only supports a single extension target.
# ...
[[extensions.targeting]]
target = "purchase.checkout.block.render"
module = "./Block.jsx"
# ...
// ...
export default reactExtension(
'purchase.checkout.block.render',
<Extension />,
);
function Extension() {
// ...
}
You can support multiple extension targets within a single configuration file. However, you must provide a separate file per extension target using the `export default` declaration.
# ...
[[extensions.targeting]]
target = "purchase.checkout.actions.render-before"
module = "./Actions.jsx"
[[extensions.targeting]]
target = "purchase.checkout.shipping-option-item.render-after"
module = "./ShippingOptions.jsx"
# ...
// ...
// ./Actions.jsx
export default reactExtension(
'purchase.checkout.actions.render-before',
<Extension />,
);
function Extension() {
// ...
}
// ...
// ./ShippingOptions.jsx
export default reactExtension(
'purchase.checkout.shipping-option-item.render-after',
<Extension />,
);
function Extension() {
// ...
}
[Targets](/docs/api/checkout-ui-extensions/extension-targets-overview) represent where your checkout UI extension will be injected. You may have one or many targets defined in your app extension configuration using the `targeting` field. Along with the `target`, Shopify needs to know which code to execute for it. You specify the path to your code file by using the `module` property.
Defines the [capabilities](/docs/api/checkout-ui-extensions/apis/standardapi#properties-propertydetail-extension) associated with your extension. | Property | Description | |---|---| | [`api_access`](#api-access) | Allows your extension to query the Storefront API. | [`network_access`](#network-access) | Allows your extension make external network calls. | [`block_progress`](#block-progress) | States that your extension might block the buyer's progress. | [`collect_buyer_consent`](#collect-buyer-consent) | Allows your extension to collect buyer consent for specific policies such as SMS marketing.
# ...
[extensions.capabilities]
api_access = true
network_access = true
block_progress = true
[extensions.capabilities.collect_buyer_consent]
sms_marketing = true
customer_privacy = true
# ...
The following section describes the use cases of the `api_access` capability and the [Storefront API](/api/storefront) access scopes.
# ...
[extensions.capabilities]
api_access = true
# ...
The following section describes use cases for requesting network access, alternatives to requesting network access, and steps for completing a request for network access. > Caution: > If your extension specifies the `network_access` capability, you must request access in order to publish your extension.
# ...
[extensions.capabilities]
network_access = true
# ...
The following section describes blocking the buyer's progress through checkout, and how you can detect whether the merchant has allowed it.
# ...
[extensions.capabilities]
block_progress = true
# ...
If your extension utilizes the [ConsentCheckbox](/docs/api/checkout-ui-extensions/components/forms/consentcheckbox) or [ConsentPhoneField](/docs/api/checkout-ui-extensions/components/forms/consentphonefield) components to render a customized UI for collecting buyer consent, you must first declare that capability in your configuration file.
# ...
[extensions.capabilities.collect_buyer_consent]
sms_marketing = true
customer_privacy = true
# ...
Defines the [metafields](/docs/apps/custom-data/metafields) that are available to your extension. Each extension target uses the metafields defined in `[[extensions.metafields]]` unless they specify their own `[[extensions.targeting.metafields]]`. Supported resource metafield types include: | Resource | Description | |---| --- | | `cart` | The cart associated with the current checkout. | | `company` | The company for B2B checkouts. | | `companyLocation` | The company's location for B2B checkouts. | | `customer` | The customer account that is interacting with the current checkout. | | `product` | The products that the customer intends to purchase. | | `shop` | The shop that is associated with the current checkout. | | `shopUser` | The Shop App user that is associated with the current checkout if there is one. | | `variant` | The product variants that the customer intends to purchase. | You retrieve these metafields in your extension by reading [`appMetafields`](/docs/api/checkout-ui-extensions/apis/standardapi#properties-propertydetail-appmetafields). > Tip: > You may write to `cart` metafields by using [`applyMetafieldsChange`](/docs/api/checkout-ui-extensions/apis/checkoutapi#properties-propertydetail-applymetafieldchange) with `type: "updateCartMetafield"`.
# ...
# The metafields for the extension
[[extensions.metafields]]
namespace = "my-namespace"
key = "my-key"
[[extensions.metafields]]
namespace = "my-namespace"
key = "my-other-key"
[[extensions.targeting]]
target = "purchase.checkout.actions.render-before"
module = "./Actions.jsx"
# For the above target, use these metafields
[[extensions.targeting.metafields]]
namespace = "my-namespace"
key = "my-target-key"
[[extensions.targeting]]
target = "purchase.checkout.shipping-option-item.render-after"
module = "./ShippingOptions.jsx"
The settings for a checkout UI extension define a set of fields that the merchant can set a value for from the [checkout editor](/apps/checkout/test-ui-extensions#test-the-extension-in-the-checkout-editor). You can use validation options to apply additional constraints to the data that the setting can store, such as a minimum or maximum value. Each settings definition can include up to 20 settings. > Note: > All setting inputs are optional. You should code the extension so that it still works if the merchant hasn't set a value for the setting.
The following example shows a settings definition that defines a setting named `banner_title` of type `single_line_text_field`. When the merchant sets a value for this setting from the checkout editor, Shopify validates that the provided value is between 5 and 20 characters in length Learn more about the settings api by completing our [custom banners example](/apps/checkout/custom-banners/add-custom-banner).
api_version = "2023-07"
[[extensions]]
type = "ui_extension"
name = "My checkout extension"
handle = "checkout-ui"
[extensions.settings]
[[extensions.settings.fields]]
key = "banner_title"
type = "single_line_text_field"
name = "Banner title"
description = "Enter a title for the banner."
[[extensions.settings.fields.validations]]
name = "min"
value = "5"
[[extensions.settings.fields.validations]]
name = "max"
value = "20"
For specific targets, you must provide the URL of assets or pages loaded by UI components within its extension. This allows Shopify to preload them as early as possible and ensure a performant experience for buyers. Currently, the only supported component is `chat`. The URL for the iframe used in this extension target. The URL can be absolute or relative. Relative URLs are resolved against the app URL. For example, * if the app URL is `https://example.com` and `chat = "/my-chat-application"`, the resolved URL will be `https://example.com/my-chat-application`. * if `chat = "https://my-chat-application.com"`, the resolved URL will be `https://my-chat-application.com`.
# ...
[[extensions.targeting]]
target = "purchase.checkout.chat.render"
module = "./Block.jsx"
[extensions.targeting.preloads]
chat = "https://my-chat-application.com"
# ...
// ...
export default reactExtension(
'purchase.checkout.chat.render',
<Extension />,
);
function Extension() {
// ...
}