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 (24)

Supported targets

Anchor to PropertiesProperties

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

Anchor to settings settings <> required: Merchant-defined configuration values for your extension, as specified in the settings definition of your shopify.extension.toml file. Settings update in real time as merchants edit them in the extension editor. The value is empty until a merchant sets it.

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.
```
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.
```
() => 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.
```
(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.
```
T
```

ExtensionSettings

The merchant-defined setting values for the extension.

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

const bannerTitle =

shopify.settings.value?.banner_title || '';

return <s-banner title={bannerTitle} />;

}

Examples

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.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const bannerTitle =
    shopify.settings.value?.banner_title || '';

  return <s-banner title={bannerTitle} />;
}

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.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const showLoyaltyBadge =
    shopify.settings.value?.show_loyalty_badge ??
    false;

  if (!showLoyaltyBadge) {
    return null;
  }

  return (
    <s-badge tone="auto">
      Loyalty member
    </s-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?