---
title: Settings
description: The API for interacting with merchant settings.
api_version: 2025-10
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
---

# SettingsAPI

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

  ```ts
  (fn: (value: T) => void) => () => void
  ```

* value

  ```ts
  T
  ```

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



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

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



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

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

## Examples

Define merchant settings

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

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

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

## Related

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/targets)

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

[![](https://shopify.dev/images/icons/32/apps.png)![](https://shopify.dev/images/icons/32/apps-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/components)

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

[![](https://shopify.dev/images/icons/32/gear.png)![](https://shopify.dev/images/icons/32/gear-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)

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

[![](https://shopify.dev/images/icons/32/tutorial.png)![](https://shopify.dev/images/icons/32/tutorial-dark.png)](https://shopify.dev/apps/checkout)

[LearnTutorials](https://shopify.dev/apps/checkout)