---
title: Settings API
description: >-
  The Settings API lets you read the values that merchants configure for your
  extension in the [checkout and accounts
  editor](https://help.shopify.com/manual/checkout-settings/customize-checkout-configurations/checkout-editor).
  Use this API to make your extension customizable.
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/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# Settings API

The Settings API lets you read the values that merchants configure for your extension in the [checkout and accounts editor](https://help.shopify.com/manual/checkout-settings/customize-checkout-configurations/checkout-editor). Use this API to make your extension customizable. Merchants define values like banner titles, feature toggles, or thresholds, and your extension reads them at runtime. Learn how to [define settings in your configuration](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07#configuration).

### Use cases

* **Display merchant-customized content**: Read settings like banner titles, welcome messages, or promotional text that merchants configure without needing to update your extension's code.
* **Toggle extension features**: Use boolean settings to let merchants enable or disable specific behaviors in your extension, such as showing a loyalty badge or hiding certain sections.
* **Configure thresholds and limits**: Let merchants define numeric values like minimum order amounts for displaying a message, or the number of items to show in a list.

### Support Targets (25)

### Supported targets

* Customer​Account::Kitchen​Sink
* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

### Properties

The Settings API object provides access to merchant-configured settings for customer account extensions. Access the following properties on the API object to read the values that merchants define for your extension.

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

Examples

### Examples

* #### Read a merchant-configured banner title

  ##### Description

  Access a merchant-defined setting value and use it to customize a banner component. This example reads the \`banner\_title\` setting from \`shopify.settings.value\` and displays it in an \`s-banner\` component.

  ##### React

  ```tsx
  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} />;
  }
  ```

  ##### TS

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

* #### Show or hide content with a setting

  ##### Description

  Conditionally render content based on a merchant-configured on/off setting. This example reads the \`show\_loyalty\_badge\` setting and only displays a badge when the merchant has enabled it.

  ##### React

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

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

  function Extension() {
    const {show_loyalty_badge} = useSettings();
    const showLoyaltyBadge =
      show_loyalty_badge ?? false;

    if (!showLoyaltyBadge) {
      return null;
    }

    return (
      <Badge tone="success">Loyalty member</Badge>
    );
  }
  ```

  ##### TS

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

  export default extension(
    'customer-account.order-status.block.render',
    (root, {settings}) => {
      const showLoyaltyBadge =
        settings.current.show_loyalty_badge ?? false;

      const badge = root.createComponent(
        Badge,
        {tone: 'success'},
        'Loyalty member',
      );

      if (showLoyaltyBadge) {
        root.appendChild(badge);
      }

      settings.subscribe((newSettings) => {
        const show =
          newSettings.show_loyalty_badge ?? false;

        if (show && !badge.parent) {
          root.appendChild(badge);
        } else if (!show && badge.parent) {
          root.removeChild(badge);
        }
      });
    },
  );
  ```

***

## Best practices

* **Provide sensible defaults**: Always use a fallback value when reading settings with `shopify.settings.value` in case the merchant hasn't configured a value yet.
* **Keep settings simple**: Define only the settings that merchants genuinely need to customize. Too many settings can overwhelm merchants in the [checkout and accounts editor](https://help.shopify.com/manual/checkout-settings/customize-checkout-configurations/checkout-editor).
* **Use descriptive names and descriptions**: Give each setting a clear `name` and `description` in your TOML file so merchants understand what each field controls.
* **Validate setting values**: Use the [validations](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#validation-options) property in your TOML configuration to enforce constraints like minimum and maximum lengths or allowed values.

***

## Limitations

* Settings are read-only in your extension. You can't programmatically update setting values. Merchants must change them in the [checkout and accounts editor](https://help.shopify.com/manual/checkout-settings/customize-checkout-configurations/checkout-editor).
* Setting values are only available after the extension has loaded. Accessing `shopify.settings.value` before initialization returns `undefined`.
* Settings don't support complex data types like arrays or nested objects. Refer to [supported setting types](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#supported-setting-types) for the full list of available types.

***