---
title: Settings API
description: The API for interacting with merchant settings.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/platform-apis/settings-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/platform-apis/settings-api.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-10/upgrading-to-2025-10) to upgrade your extension.

# Settings API

The API for interacting with merchant settings.

## StandardApi

The base API object provided to this and other `customer-account` extension targets.

* **settings**

  **StatefulRemoteSubscribable\<ExtensionSettings>**

  **required**

  The merchant-configured [settings](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07#configuration) for this extension. Settings are empty until the merchant configures them, and values update in real time as the merchant saves changes.

### ExtensionSettings

The merchant-defined setting values for the extension, as configured in the \[\`shopify.extension.toml\`]\(/docs/api/customer-account-ui-extensions/2025-07#configuration) file.

* \[key: string]

  ```ts
  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, as configured in the \[\`shopify.extension.toml\`]\(/docs/api/customer-account-ui-extensions/2025-07#configuration) file.

* \[key: string]

  ```ts
  string | number | boolean | undefined
  ```

Examples

### Examples

* #### Accessing merchant settings

  ##### React

  ```jsx
  import {
    reactExtension,
    Banner,
    useSettings,
  } from '@shopify/ui-extensions-react/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const {banner_title} = useSettings();
    return <Banner title={banner_title} />;
  }
  ```

  ##### JavaScript

  ```js
  import {
    extension,
    Banner,
  } from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, {settings}) => {
      const banner = root.createComponent(Banner, {
        title: settings.current.banner_title,
      });

      // When the merchant updates the banner title in the checkout editor, re-render the banner
      settings.subscribe((newSettings) => {
        banner.updateProps({
          title: newSettings.banner_title,
        });
      });

      root.appendChild(banner);
    },
  );
  ```

* #### Define merchant settings

  ##### Description

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

  ##### shopify.extension.toml

  ```toml
  api_version = "unstable"

  [[extensions]]
  name = "My customer account ui extension"
  handle = "customer-account-ui"
  type = "ui_extension"

    [[extensions.targeting]]
    target = "customer-account.order-status.block.render"
    module = "./Extension.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"
  ```