Skip to main content

Configuration

When you create a customer account UI extension, an app extension configuration shopify.extension.toml file is automatically generated in your extension's directory.

This guide describes extension targeting, capabilities, metafields, and the settings you can configure in the app extension configuration.

Anchor to how-it-worksHow 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.

Learn moreApp extension configuration

Shopify.extension.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"

Anchor to targetsTargets

Targets 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 for your extension.

Anchor to targets-supporting-a-single-extension-targetSupporting a single extension target

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

Anchor to targets-supporting-multiple-extension-targetsSupporting 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.

Single extension target

# ...

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

# ...

Anchor to capabilitiesCapabilities

Defines the capabilities associated with your extension.

PropertyDescription
api_accessAllows your extension to query the Storefront API.
network_accessAllows your extension make external network calls.
collect_buyer_consentAllows your extension to collect buyer consent for specific policies such as SMS marketing.

Capabilities

shopify.extension.toml

# ...

[extensions.capabilities]
api_access = true
network_access = true

[extensions.capabilities.collect_buyer_consent]
customer_privacy = true

# ...


Anchor to api-accessStorefront API access

The following section describes the use cases of the api_access capability and the Storefront API access scopes.

SeeAPI access examples

Anchor to When to use Storefront API accessWhen to use Storefront API access

API access is used when your extension needs to retrieve data from the Storefront API. 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.

Anchor to Methods for accessing the Storefront APIMethods for accessing the Storefront API

Enabling the api_access capability allows you to use the Order Status API query method and the global fetch to retrieve data from the Storefront API 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 capability.

Anchor to Storefront API access scopesStorefront 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

Enable Storefront API access

shopify.extension.toml

# ...

[extensions.capabilities]
api_access = true

# ...

Anchor to network-accessNetwork 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.

Anchor to When to request network accessWhen 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.

Anchor to Alternatives to network accessAlternatives 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 to write to metafields on the customer, order, company, or company location.

An app with the ability to query the Admin API can also write to metafields 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.

Anchor to Complete a request for network accessComplete a request for network access

  1. Go to your Partner Dashboard.

  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.

Anchor to Required CORS headersRequired CORS headers

Since UI extensions run in a Web Worker, 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) for null origins by including this response header:

Access-Control-Allow-Origin: *

Anchor to App ProxyApp Proxy

UI extensions can make fetch requests to App Proxy 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 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. Specifically, CONNECT and TRACE are unsupported.

Anchor to Security considerationsSecurity 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 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.

Enable network access

shopify.extension.toml

# ...

[extensions.capabilities]
network_access = true

# ...

Anchor to collect-buyer-consentCollect buyer consent

If your extension utilizes the Customer Privacy API to collecting buyer consent, you must first declare that capability in your configuration file.

Anchor to Customer PrivacyCustomer 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.

Collect buyer consent

shopify.extension.toml

# ...

[extensions.capabilities.collect_buyer_consent]
customer_privacy = true

# ...


Anchor to metafieldsMetafields

All customer account UI extension targets can read and write to metafields using the Customer Account API. Learn more about writing to metafields.

Access to metafields on a read-only basis through the Order Status API is available to order status targets and is defined in your configuration. Customer account UI extensions are configured for metafields similarly to checkout UI extensions. Learn more.

Anchor to settings-definitionSettings 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. 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.

Anchor to PropertiesProperties

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

PropertyRequired?DescriptionExample
keyYesThe 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"
typeYesThe type of setting.
"single_line_text_field"
nameYesThe name of the setting. name is displayed to the merchant in the checkout editor.
"Banner title"
descriptionNoThe description of the setting. description is displayed to the merchant in the checkout editor.
"Enter a title for the banner."
validationsNoConstraints on the setting input that Shopify validates.
validations: 
 name = "max",
 value = "25"

Anchor to Supported setting typesSupported 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:

TypeDescriptionExample value
booleanA true or false value.
true
dateA date in ISO 8601 format without a presumed time zone.
2022-02-02
date_timeA date and time in ISO 8601 format without a presumed time zone.
2022-01-01T12:30:00
single_line_text_fieldA single line string.
Canada
multi_line_text_fieldA multi-line string.
Canada
United States
Brazil
Australia
number_integerA whole number in the range of +/-9,007,199,254,740,991.
10
number_decimalA number with decimal places in the range of +/-9,999,999,999,999.999999999.
10.4
variant_referenceA globally-unique identifier (GID) for a product variant.
gid://shopify/ProductVariant/1
Anchor to Validation optionsValidation 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 optionDescriptionSupported typesExample
Minimum lengthThe minimum length of a text value.
  • single_line_text_field
  • multi_line_text_field
[[extensions.settings.fields.validations]]
 name = "min"
 value = "8"
Maximum lengthThe maximum length of a text value.
  • single_line_text_field
  • multi_line_text_field
[[extensions.settings.fields.validations]]
 name = "max"
 value = "25"
Regular expressionA regular expression. Shopify supports RE2.
  • single_line_text_field
  • multi_line_text_field
[[extensions.settings.fields.validations]]
 name = "regex"
 value = "(@)(.+)$"
ChoicesA 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 dateThe minimum date in ISO 8601 format.date
[[extensions.settings.fields.validations]]
 name = "min"
 value = "2022-01-01"
Maximum dateThe maximum date in ISO 8601 format.date
[[extensions.settings.fields.validations]]
 name = "max"
 value = "2022-03-03"
Minimum datetimeThe minimum date and time in ISO 8601 format.date_time
[[extensions.settings.fields.validations]]
 name = "min"
 value = "2022-03-03T16:30:00"
Maximum datetimeThe maximum date and time in ISO 8601 format.date_time
[[extensions.settings.fields.validations]]
 name = "max"
 value = "2022-03-03T17:30:00"
Minimum integerThe minimum integer number.number_integer
[[extensions.settings.fields.validations]]
 name = "min"
 value = "9"
Maximum integerThe maximum integer number.number_integer
[[extensions.settings.fields.validations]]
 name = "max"
 value = "15"
Minimum decimalThe minimum decimal number.number_decimal
[[extensions.settings.fields.validations]]
 name = "min"
 value = "0.5"
Maximum decimalThe maximum decimal number.number_decimal
[[extensions.settings.fields.validations]]
 name = "max"
 value = "1.99"
Maximum precisionThe maximum number of decimal places to store for a decimal number.number_decimal
[[extensions.settings.fields.validations]]
 name = "max_precision"
 value = "2"
Anchor to example-settings-definitionExample 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


SeeSettings example code
Example settings
shopify.extension.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"