---
title: Configuration
description: |
  
  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.
api_version: 2025-10
api_name: customer-account-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/configuration
  md: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/configuration.md
---

# Configuration

When you create a [customer account UI extension](https://shopify.dev/api/customer-account-ui-extensions/), an [app extension configuration](https://shopify.dev/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.

***

## How it works

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.

Tip

You can configure more than one type of extension within a configuration file.

[![](https://shopify.dev/images/icons/32/gear.png)![](https://shopify.dev/images/icons/32/gear-dark.png)](https://shopify.dev/docs/apps/app-extensions/configuration)

[Learn moreApp extension configuration](https://shopify.dev/docs/apps/app-extensions/configuration)

### Examples

* #### shopify.extension.toml

  ##### shopify.extension.toml

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

## Targets

[Targets](https://shopify.dev/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.

For block extension targets, you can [define the default placement](https://shopify.dev/docs/apps/build/customer-accounts/extension-placement#define-default-placement) for your extension.

Supporting a single extension target

Your code should have a default export if it only supports a single extension target.

Supporting multiple extension targets

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.

### Examples

* #### Single extension target

  ##### shopify.extension.toml

  ```toml
  # ...

  [[extensions.targeting]]
  target = "customer-account.order-status.block.render"
  module = "./Extension.jsx"

  # ...
  ```

  ##### Extension.jsx

  ```jsx
  // ...

  export default async () => {
    render(<Extension />, document.body);
  };

  function Extension() {
    // ...
  }
  ```

## Capabilities

Defines the [capabilities](https://shopify.dev/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. |
| [`collect_buyer_consent`](#collect-buyer-consent) | Allows your extension to collect buyer consent for specific policies such as SMS marketing. |

### Examples

* #### shopify.extension.toml

  ##### Default

  ```toml
  # ...

  [extensions.capabilities]
  api_access = true
  network_access = true

  [extensions.capabilities.collect_buyer_consent]
  customer_privacy = true

  # ...
  ```

## Storefront API access

The following section describes the use cases of the `api_access` capability and the [Storefront API](https://shopify.dev/api/storefront) access scopes.

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/storefront-api#examples)

[SeeAPI access examples](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/storefront-api#examples)

### When to use Storefront API access

API access is used when your extension needs to retrieve data from the [Storefront API](https://shopify.dev/api/storefront). For example, you may need to fetch product data, check the product tags on an item in the order summary.

Tip

Shopify handles the authentication for all API calls from an extension.

### Methods for accessing the Storefront API

Enabling the `api_access` capability allows you to use the Order Status API [`query`](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/storefront-api#orderstatusapi-propertydetail-query) method and the global `fetch` to retrieve data from the [Storefront API](https://shopify.dev/api/storefront) without manually managing token aquisition and refresh.

`query` lets you request a single GraphQL response from the Storefront API.

If you prefer to construct GraphQL requests yourself or you would like to use a full-featured GraphQL client such as Apollo or urql, our custom `fetch` global automatically appends the required access tokens.

The GraphQL client of your choice shouldn’t use any DOM APIs, as they aren’t available in a customer account UI extension's Web Worker.

Note

Both `query` and `fetch` will work for calling the Storefront API with the `api_access` capability enabled. If you are using `fetch` to get data external to Shopify, refer to the [`network_access`](https://shopify.dev/api/customer-account-ui-extensions/configuration#network-access) capability.

### Storefront API access scopes

Your extensions will have the following unauthenticated access scopes to the Storefront API:

* `unauthenticated_read_product_publications`
* `unauthenticated_read_collection_publications`
* `unauthenticated_read_product_listings`
* `unauthenticated_read_product_tags`
* `unauthenticated_read_selling_plans`
* `unauthenticated_read_collection_listings`
* `unauthenticated_read_metaobjects`

### Examples

* #### shopify.extension.toml

  ##### Default

  ```toml
  # ...

  [extensions.capabilities]
  api_access = true

  # ...
  ```

## Network access

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.

### When to request network access

If you need to get data that you can't currently get from Shopify, then you should request network access. For example, you might need to fetch additional data to render loyalty points.

### Alternatives to network access

Instead of fetching data with an external network call, consider retrieving the data from a metafield. Your app can use the [Customer Account API](https://shopify.dev/docs/api/customer) to write to [metafields](https://shopify.dev/docs/api/customer/latest/objects/Metafield) on the customer, order, company, or company location.

An app with the ability to query the Admin API can also write to [metafields](https://shopify.dev/api/admin-graphql/latest/objects/metafield) on the shop or product.

Retrieving data from metafields is faster because it doesn't require an external network call. Instead, you can rely on Shopify for the uptime, scaling, and durability of the data storage.

### Complete a request for network access

1. Go to your [Partner Dashboard](https://partners.shopify.com/current/apps).

2. Click the name of the app that you want to change.

3. Click **API access**.

4. Under **Allow network access in checkout and account UI extensions**, click **Allow network access**

   Your request is automatically approved and your app is immediately granted the approval scope that's required for your customer account UI extension to make external network calls.

5. Add `network_access = true` to the `[extensions.capabilities]` section of your extension's configuration file.

### Required CORS headers

Since UI extensions run in a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API), they have a null origin. They do not share the storefront or customer account's origin. For network calls to succeed, your server must support [cross-origin resource sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) for null origins by including this response header:

`Access-Control-Allow-Origin: *`

### App Proxy

UI extensions can make fetch requests to [App Proxy](https://shopify.dev/docs/apps/online-store/app-proxies) URLs, but there are some differences and limitations related to the security context within which UI extensions run.

UI extension requests made to the App Proxy will execute as CORS requests. See *Required CORS headers* above for information about requirements related to CORS.

UI extension requests made to the App Proxy will not assign the `logged_in_customer_id` query parameter. Instead use a [session token](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/standardapi#properties-propertydetail-sessiontoken) which provides the `sub` claim for the logged in customer.

UI extension requests made to the App Proxy of password protected shops is not supported. Extension requests come from a web worker which does not share the same session as the parent window.

The App Proxy doesn't handle all [HTTP request methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). Specifically, `CONNECT` and `TRACE` are unsupported.

### Security considerations

When processing HTTP requests on your API server, you cannot guarantee that your own extension will have made every request. When responding with sensitive data, keep in mind that requests could originate from anywhere on the Internet.

Your extension can pass a [session token](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/session-token) to your API server but this only guarantees the integrity of its claims. It does not guarantee the request itself originated from Shopify. For example, your API server could trust the session token's `sub` claim (the customer ID) but it could not trust a `?customer_id=` query parameter.

### Examples

* #### shopify.extension.toml

  ##### Default

  ```toml
  # ...

  [extensions.capabilities]
  network_access = true

  # ...
  ```

## Collect buyer consent

If your extension utilizes the [Customer Privacy API](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/customer-privacy) to collecting buyer consent, you must first declare that capability in your configuration file.

### Customer Privacy

In order to collect customer privacy consent, you'll need to add `customer_privacy = true` in your toml configuration. This will let you use our [Customer Privacy API](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/customer-privacy).

### Examples

* #### shopify.extension.toml

  ##### Default

  ```toml
  # ...

  [extensions.capabilities.collect_buyer_consent]
  customer_privacy = true

  # ...
  ```

## Metafields

All customer account UI extension [targets](https://shopify.dev/docs/api/customer-account-ui-extensions/targets) can read and write to metafields using the [Customer Account API](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/customer-account-api). Learn more about [writing to metafields](https://shopify.dev/docs/apps/build/customer-accounts/metafields).

Access to metafields on a read-only basis through the [Order Status API](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/order-status-api/metafields) is available to order status [targets](https://shopify.dev/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](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#metafields).

## Settings definition

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](https://shopify.dev/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](https://shopify.dev/api/customer-account-ui-extensions/targets).

### Properties

The following table describes the properties that you can use to define a setting:

| Property | Required? | Description | Example |
| - | - | - | - |
| `key` | Yes | The key of the setting. When a merchant configures a value for this setting, the value will be exposed under this `key` when running your extension | ```
"banner_title"
``` |
| `type` | Yes | The [type](#supported-setting-types) of setting. | ```
"single_line_text_field"
``` |
| `name` | Yes | The name of the setting. `name` is displayed to the merchant in the checkout editor. | ```
"Banner title"
``` |
| `description` | No | The description of the setting. `description` is displayed to the merchant in the checkout editor. | ```
"Enter a title for the banner."
``` |
| `validations` | No | Constraints on the setting input that Shopify validates. | ```
validations: 
 name = "max",
 value = "25"
``` |

### Supported setting types

The setting type determines the type of information that the setting can store. The setting types have built-in validation on the setting input.

Settings can have the following types:

| Type | Description | Example value |
| - | - | - |
| `boolean` | A true or false value. | ```
true
``` |
| `date` | A date in ISO 8601 format without a presumed time zone. | ```
2022-02-02
``` |
| `date_time` | A date and time in ISO 8601 format without a presumed time zone. | ```
2022-01-01T12:30:00
``` |
| `single_line_text_field` | A single line string. | ```
Canada
``` |
| `multi_line_text_field` | A multi-line string. | ```
Canada
United States
Brazil
Australia
``` |
| `number_integer` | A whole number in the range of +/-9,007,199,254,740,991. | ```
10
``` |
| `number_decimal` | A number with decimal places in the range of +/-9,999,999,999,999.999999999. | ```
10.4
``` |
| `variant_reference` | A globally-unique identifier (GID) for a product variant. | ```
gid://shopify/ProductVariant/1
``` |

### Validation options

Each setting can include validation options. Validation options enable you to apply additional constraints to the data that a setting can store, such as a minimum or maximum value, or a regular expression. The setting's `type` determines the available validation options.

You can include a validation option for a setting using the validation `name` and a corresponding `value`. The appropriate value depends on the setting type to which the validation applies.

The following table outlines the available validation options with supported types for applying constraints to a setting:

| Validation option | Description | Supported types | Example |
| - | - | - | - |
| Minimum length | The minimum length of a text value. | * `single_line_text_field`
* `multi_line_text_field` | ```
[[extensions.settings.fields.validations]]
 name = "min"
 value = "8"
``` |
| Maximum length | The maximum length of a text value. | - `single_line_text_field`
- `multi_line_text_field` | ```
[[extensions.settings.fields.validations]]
 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` | ```
[[extensions.settings.fields.validations]]
 name = "regex"
 value = "(@)(.+)$"
``` |
| Choices | A list of up to 128 predefined options that limits the values allowed for the metafield. | `single_line_text_field` | ```
[[extensions.settings.fields.validations]]
 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` | ```
[[extensions.settings.fields.validations]]
 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` | ```
[[extensions.settings.fields.validations]]
 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` | ```
[[extensions.settings.fields.validations]]
 name = "min"
 value = "2022-03-03T16:30: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` | ```
[[extensions.settings.fields.validations]]
 name = "max"
 value = "2022-03-03T17:30:00"
``` |
| Minimum integer | The minimum integer number. | `number_integer` | ```
[[extensions.settings.fields.validations]]
 name = "min"
 value = "9"
``` |
| Maximum integer | The maximum integer number. | `number_integer` | ```
[[extensions.settings.fields.validations]]
 name = "max"
 value = "15"
``` |
| Minimum decimal | The minimum decimal number. | `number_decimal` | ```
[[extensions.settings.fields.validations]]
 name = "min"
 value = "0.5"
``` |
| Maximum decimal | The maximum decimal number. | `number_decimal` | ```
[[extensions.settings.fields.validations]]
 name = "max"
 value = "1.99"
``` |
| Maximum precision | The maximum number of decimal places to store for a decimal number. | `number_decimal` | ```
[[extensions.settings.fields.validations]]
 name = "max_precision"
 value = "2"
``` |

## Example settings definition

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

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/order-status-api/settings#examples)

[SeeSettings example code](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/order-status-api/settings#examples)

### Examples

* #### shopify.extension.toml

  ##### Default

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