--- 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: 2026-04 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/settings-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/settings-api.md --- # 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/latest#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 (24) ### Supported targets * [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/footer#footer-render-after-) * [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-announcement-) * [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-block-) * [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-menu-item-) * [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-) * [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#customer-account-full-page-) * [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-page-default-targets-) * [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-announcement-) * [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-block-) * [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/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/2026-04/targets/profile-page-b2b#company-location-staff-render-after-) * customer-account.​profile.​payment.​render-after ### Properties The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#target-apis-define-what-your-extension-does) 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. * **settings** **SubscribableSignalLike\** **required** Merchant-defined configuration values for your extension, as specified in the [settings definition](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/configuration#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. ```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 ``` * 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. Examples ### 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 ```tsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const bannerTitle = shopify.settings.value?.banner_title || ''; return ; } ``` * #### ##### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const showLoyaltyBadge = shopify.settings.value?.show_loyalty_badge ?? false; if (!showLoyaltyBadge) { return null; } return ( Loyalty member ); } ``` *** ## 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. ***