Configuration

When you create a [checkout UI extension](/api/checkout-ui-extensions/), the `shopify.ui.extension.toml` file is automatically generated in your checkout UI extension directory. This guide describes the properties that you can configure in `shopify.ui.extension.toml`.

How it works

How it works

You define properties for your checkout UI extension in the extension configuration file. The `shopify.ui.extension.toml` file contains the extension's configuration, which include the extension name, extension points, metafields, capabilities, and settings definition. When an extension is published to Shopify, the contents of the settings file are pushed alongside the extension.

type = "checkout_ui_extension"
name = "my-checkout-extension"

extension_points = [
  'Checkout::Dynamic::Render'
]

[[metafields]]
namespace = "my-namespace"
key = "my-key"

[[metafields]]
namespace = "my-namespace"
key = "my-other-key"

[capabilities]
network_access = true
block_progress = true
api_access = true

[settings]
  [[settings.fields]]
  key = "field_key"
  type = "boolean"
  name = "field-name"
  [[settings.fields]]
  key = "field_key_2"
  type = "number_integer"
  name = "field-name-2"

Configuration properties

Configuration properties

| Property | Required? | Description | |---|---|---| | `type` | Yes | The type of extension. For checkout UI extensions, this value is `checkout_ui_extension`. | | `name` | Yes | The name of the checkout UI extension. | | `extension_points` | Yes | The [pre-defined points](/docs/api/checkout-ui-extensions/extension-points-overview) within checkout that your extension will render to. These values must match how your extension calls `extend()` or `render()`.

For example, if your extension calls `extend('Checkout::Dynamic::Render', () => {})` then your config must specify `Checkout::Dynamic::Render`. | | `metafields` | Yes | The metafields that your extension [needs to read](/docs/api/checkout-ui-extensions/apis/standardapi#properties-propertydetail-appmetafields).

You can specify up to five `key` and `namespace` pairs in the settings file. When the extension is executed, Shopify looks for the metafields in each resource and returns their contents. | | `capabilities` | No | Defines the [capabilities](/docs/api/checkout-ui-extensions/apis/standardapi#properties-propertydetail-extension) associated with the UI extension.

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

Storefront API access

Storefront API access

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

type = "checkout_ui_extension"
name = "my-checkout-extension"

# ...

[capabilities]
api_access = true

Network access

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.

type = "checkout_ui_extension"
name = "my-checkout-extension"

# ...

[capabilities]
network_access = true

Block progress

Block progress

The following section describes blocking the buyer's progress through checkout, and how you can detect whether the merchant has allowed it.

type = "checkout_ui_extension"
name = "my-checkout-extension"

# ...

[capabilities]
block_progress = true

Settings definition

Settings definition

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.

Example settings definition

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 Learn more about the settings api by completing our [custom banners example](/apps/checkout/custom-banners/add-custom-banner).

[settings]
  [[settings.fields]]
  key = "banner_title"
  type = "single_line_text_field"
  name = "Banner title"
  description = "Enter a title for the banner."
    [[settings.fields.validations]]
    name = "min"
    value = "5"
    [[settings.fields.validations]]
    name = "max"
    value = "20"