When you create a [customer account UI extension](/api/customer-account-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 customer account UI extension in the extension configuration file. The `shopify.extension.toml` file contains the extension's configuration, which includes the extension name, targets, capabilities, and settings. When an extension is published to Shopify, the contents of the settings file are pushed alongside the extension.
api_version = "unstable"
[[extensions]]
type = "ui_extension"
name = "My customer account extension"
handle = "customer-account-ui"
[[extensions.targeting]]
target = "customer-account.order-status.block.render"
module = "./OrderStatusBlockExtension.jsx"
[extensions.capabilities]
network_access = true
api_access = 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 = "customer-account.order-status.block.render"
module = "./Extension.jsx"
# ...
// ...
export default reactExtension(
'customer-account.order-status.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 = "customer-account.page.render"
module = "./FullPageExtension.jsx"
[[extensions.targeting]]
target = "customer-account.order-status.block.render"
module = "./BlockExtension.jsx"
# ...
// ...
// ./FullPageExtension.jsx
export default reactExtension(
'customer-account.page.render',
<FullPageExtension />,
);
function FullPageExtension() {
// ...
}
// ...
// ./BlockExtension.jsx
export default reactExtension(
'customer-account.order-status.block.render',
<BlockExtension />,
);
function BlockExtension() {
// ...
}
[Targets](/docs/api/customer-account-ui-extensions/extension-targets-overview) represent where your customer account 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/customer-account-ui-extensions/apis/extension#standardapi-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.
# ...
[extensions.capabilities]
api_access = true
network_access = 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
# ...
All customer account UI extension [targets](/docs/api/customer-account-ui-extensions/targets) can read and write to metafields using the [Customer Account API](/docs/api/customer-account-ui-extensions/apis/customer-account-api). Learn more about [writing to metafields](/docs/apps/build/customer-accounts/metafields). Access to metafields on a read-only basis through the [Order Status API](/docs/api/customer-account-ui-extensions/apis/order-status-api/metafields) is available to order status [targets](/api/customer-account-ui-extensions/targets) and is defined in your configuration. Customer account UI extensions are configured for metafields similarly to checkout UI extensions. [Learn more](/docs/api/checkout-ui-extensions/configuration#metafields).
The settings for a customer account UI extension define a set of fields that the merchant will be able to 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 settings are only available to order status [targets](/api/customer-account-ui-extensions/targets).
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
api_version = "unstable"
[[extensions]]
name = "My customer account ui extension"
handle = "customer-account-ui"
type = "ui_extension"
[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"