Choose a version:

Settings API

The Settings API provides access to merchant-configured values defined in your extension's shopify.extension.toml file. Use this API to read settings that merchants customize through the checkout and accounts editor, such as banner text, color choices, or feature toggles.

Settings are read-only from the extension. Merchants configure them through the checkout and accounts editor. There's no API to update settings programmatically.

Settings values are limited to strings, numbers, and booleans. Complex data structures aren't supported.

Anchor to Use casesUse cases

Display merchant-configured content: Show text, banners, or messages using values that the merchant sets in the checkout and accounts editor.
Toggle features dynamically: Use boolean settings to let merchants enable or disable extension features without code changes.
Define configurable options: Use the TOML settings definition to expose options like text fields, color pickers, and toggles that merchants can edit without code changes.

Support

Targets (33)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides settings data for the current checkout. Access the following properties on shopify to read the merchant-configured settings values. Available to purchase extension targets.

Anchor to settings settings <> required: The settings matching the settings definition written in the shopify.extension.toml file.

Refer to settings examples for more information.

Note
When an extension is being installed in the editor, the settings are empty until a merchant sets a value. In that case, this object updates in real time as a merchant fills in the settings.
Note: When an extension is being installed in the editor, the settings are empty until a merchant sets a value. In that case, this object updates in real time as a merchant fills in the settings.

SubscribableSignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends `ReadonlySignalLike` with deprecated fields that are still supported for backwards compatibility.

current
The current value of the signal. Equivalent to `.value`, accessing this property subscribes to changes when used in a reactive context.
```
T
```
destroy
Cleans up the subscription and releases any resources held by this signal. After calling `destroy()`, the signal stops receiving updates from the main thread.
```
() => Promise<void>
```
subscribe
Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.
```
(fn: (value: T) => void) => () => void
```
value
The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.
```
T
```

ExtensionSettings

The merchant-defined setting values for the extension.

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

return (

<s-banner>

{shopify.settings.value.banner_title}

</s-banner>

);

}

Examples

Description

Render merchant-configured values at runtime. This example reads `shopify.settings` and re-renders automatically when the merchant updates settings in the checkout and accounts editor.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

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

function Extension() {
  return (
    <s-banner>
      {shopify.settings.value.banner_title}
    </s-banner>
  );
}

Description

Define settings that merchants can edit in the checkout and accounts editor. See [settings](/docs/apps/build/app-extensions/configure-app-extensions#settings-definition) for details on how to define these.

shopify.extension.toml

api_version = "2026-04"

[[extensions]]
name = "My checkout extension"
handle = "checkout-ui"
uid = "fddfc370-27c7-c30f-4ee0-a927194e2accadefd40c"
type = "ui_extension"

[[extensions.targeting]]
target = "purchase.checkout.block.render"
module = "./Checkout.jsx"

[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"

Anchor to Best practicesBest practices

Provide sensible defaults for all settings: To ensure that your extension renders correctly from the first installation, always handle undefined values by falling back to a reasonable default. Settings values are undefined until the merchant configures them in the checkout and accounts editor, including during editor preview for newly installed extensions.

Was this page helpful?