---
title: Settings
description: The API for interacting with merchant settings.
api_version: 2026-01
api_name: checkout-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/settings
  md: https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/settings.md
---

# Settings

The API for interacting with merchant settings.

## StandardApi

The base API object provided to `purchase` extension targets.

* **settings**

  **SubscribableSignalLike\<ExtensionSettings>**

  **required**

  The settings matching the settings definition written in the [`shopify.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) file.

  Refer to [settings examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/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

  ```ts
  T
  ```

* destroy

  ```ts
  () => 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.

  ```ts
  (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.

  ```ts
  T
  ```

### ExtensionSettings

The merchant-defined setting values for the extension.



## use​Settings()

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

### Returns

* **Partial\<Settings extends ExtensionSettings>**

### ExtensionSettings

The merchant-defined setting values for the extension.



Examples

### 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

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

* #### 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

  ```toml
  api_version = "2026-01"

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

## Related

[Reference - Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)

[Reference - Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)

[Reference - Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)

[Learn - Tutorials](https://shopify.dev/apps/checkout)