Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Settings API

The Settings API lets you read the values that merchants configure for your extension in the checkout and accounts 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.

Anchor to Use casesUse 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

Anchor to PropertiesProperties

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.

Anchor to settings settings StatefulRemoteSubscribable<> required: The merchant-configured settings 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]
```
string | number | boolean | undefined
```

Examples

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

}

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

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

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

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

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

Anchor to Best practicesBest 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.
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 property in your TOML configuration to enforce constraints like minimum and maximum lengths or allowed values.

Anchor to LimitationsLimitations

Settings are read-only in your extension. You can't programmatically update setting values. Merchants must change them in the checkout and accounts 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 for the full list of available types.

Was this page helpful?