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

# Settings API

The API for interacting with merchant settings.

### Support Targets (33)

### Supported targets

* purchase.​address-autocomplete.​format-suggestion
* purchase.​address-autocomplete.​suggest
* purchase.​checkout.​actions.​render-before
* purchase.​checkout.​block.​render
* purchase.​checkout.​cart-line-item.​render-after
* purchase.​checkout.​cart-line-list.​render-after
* purchase.​checkout.​chat.​render
* purchase.​checkout.​contact.​render-after
* purchase.​checkout.​delivery-address.​render-after
* purchase.​checkout.​delivery-address.​render-before
* purchase.​checkout.​footer.​render-after
* purchase.​checkout.​header.​render-after
* purchase.​checkout.​payment-method-list.​render-after
* purchase.​checkout.​payment-method-list.​render-before
* purchase.​checkout.​pickup-location-list.​render-after
* purchase.​checkout.​pickup-location-list.​render-before
* purchase.​checkout.​pickup-location-option-item.​render-after
* purchase.​checkout.​pickup-point-list.​render-after
* purchase.​checkout.​pickup-point-list.​render-before
* purchase.​checkout.​reductions.​render-after
* purchase.​checkout.​reductions.​render-before
* purchase.​checkout.​shipping-option-item.​details.​render
* purchase.​checkout.​shipping-option-item.​render-after
* purchase.​checkout.​shipping-option-list.​render-after
* purchase.​checkout.​shipping-option-list.​render-before
* purchase.​thank-you.​announcement.​render
* purchase.​thank-you.​block.​render
* purchase.​thank-you.​cart-line-item.​render-after
* purchase.​thank-you.​cart-line-list.​render-after
* purchase.​thank-you.​chat.​render
* purchase.​thank-you.​customer-information.​render-after
* purchase.​thank-you.​footer.​render-after
* purchase.​thank-you.​header.​render-after

## 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/2026-04/configuration) file.

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

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

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

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

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

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