Choose a version:

Settings
API

The API for interacting with merchant settings.

Anchor to standardapiStandardApi

The base API object provided 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 will be empty until a merchant sets a value. In that case, this object will be updated in real time as a merchant fills in the settings.

SubscribableSignalLike

Represents a read-only value managed on the main thread that an extension can subscribe to. Example: Checkout uses this to manage the state of an object and communicate state changes to extensions running in a sandboxed web worker. This interface is compatible with [Preact's ReadonlySignal](https://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709). Some fields are deprecated but still supported for backwards compatibility. In version 2025-10, [`StatefulRemoteSubscribable`](https://github.com/Shopify/remote-dom/blob/03929aa8418a89d41d294005f219837582718df8/packages/async-subscription/src/types.ts#L17) was replaced with `ReadonlySignalLike`. Checkout will remove the old fields some time in the future.

current
```
T
```
destroy
```
() => Promise<void>
```
subscribe
```
(fn: (value: T) => void) => () => void
```
value
```
T
```

export interface SubscribableSignalLike<T> extends ReadonlySignalLike<T> {
  /**
   * @deprecated Use `.value` instead.
   */
  readonly current: T;
  /**
   * @deprecated No longer needed. Use Preact Signal management instead.
   */
  destroy(): Promise<void>;
}

ExtensionSettings

The merchant-defined setting values for the extension.

Record<
  string,
  string | number | boolean | undefined
>

Was this section helpful?

Anchor to useSettings
useSettings()

Returns the setting values defined by the merchant for the extension.

Anchor to useSettings-returnsReturns

Partial<Settings extends >

Was this section helpful?

Accessing merchant settings

Preact

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

Accessing merchant settings

Description

You can retrieve settings values within your extension. In React, the `useSettings()` hook re-renders your extension with the latest values. In JavaScript, subscribe to changes and update your UI directly.

Preact

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>
  );
}

Anchor to examplesExamples

Anchor to example-define-merchant-settingsDefine merchant settings

You can define settings that merchants can edit within the checkout editor. See settings for more information on how to define these.

Was this section helpful?

Define merchant settings

shopify.extension.toml

api_version = "2025-10"

[[extensions]]

name = "My checkout extension"

handle = "checkout-ui"

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"

Examples

Define merchant settings

Description

You can define settings that merchants can edit within the checkout editor. See [settings](/docs/api/checkout-ui-extensions/configuration#settings-definition) for more information on how to define these.

shopify.extension.toml

api_version = "2025-10"

[[extensions]]
name = "My checkout extension"
handle = "checkout-ui"
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"