--- title: Settings API description: The API for interacting with merchant settings. api_version: 2025-07 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/target-apis/platform-apis/settings-api md: >- https://shopify.dev/docs/api/checkout-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/checkout-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/checkout/migrate-to-web-components) to upgrade your extension. # Settings API The API for interacting with merchant settings. ### Support Targets (54) ### Supported targets * Checkout::Actions::Render​Before * Checkout::Cart​Line​Details::Render​After * Checkout::Cart​Lines::Render​After * Checkout::Contact::Render​After * Checkout::Customer​Information::Render​After * Checkout::Delivery​Address::Render​Before * Checkout::Dynamic::Render * Checkout::Pickup​Locations::Render​After * Checkout::Pickup​Locations::Render​Before * Checkout::Pickup​Points::Render​After * Checkout::Pickup​Points::Render​Before * Checkout::Reductions::Render​After * Checkout::Reductions::Render​Before * Checkout::Shipping​Method​Details::Render​After * Checkout::Shipping​Method​Details::Render​Expanded * Checkout::Shipping​Methods::Render​After * Checkout::Shipping​Methods::Render​Before * Checkout::Thank​You::Cart​Line​Details::Render​After * Checkout::Thank​You::Cart​Lines::Render​After * Checkout::Thank​You::Customer​Information::Render​After * Checkout::Thank​You::Dynamic::Render * purchase.​address-autocomplete.​format-suggestion * purchase.​address-autocomplete.​suggest * purchase.​checkout.​actions.​render-before * purchase.​checkout.​block.​render * purchase.​checkout.​cart-line-item.​render-after * purchase.​checkout.​cart-line-list.​render-after * purchase.​checkout.​chat.​render * purchase.​checkout.​contact.​render-after * purchase.​checkout.​delivery-address.​render-after * purchase.​checkout.​delivery-address.​render-before * purchase.​checkout.​footer.​render-after * purchase.​checkout.​header.​render-after * purchase.​checkout.​payment-method-list.​render-after * purchase.​checkout.​payment-method-list.​render-before * purchase.​checkout.​pickup-location-list.​render-after * purchase.​checkout.​pickup-location-list.​render-before * purchase.​checkout.​pickup-location-option-item.​render-after * purchase.​checkout.​pickup-point-list.​render-after * purchase.​checkout.​pickup-point-list.​render-before * purchase.​checkout.​reductions.​render-after * purchase.​checkout.​reductions.​render-before * purchase.​checkout.​shipping-option-item.​details.​render * purchase.​checkout.​shipping-option-item.​render-after * purchase.​checkout.​shipping-option-list.​render-after * purchase.​checkout.​shipping-option-list.​render-before * purchase.​thank-you.​announcement.​render * purchase.​thank-you.​block.​render * purchase.​thank-you.​cart-line-item.​render-after * purchase.​thank-you.​cart-line-list.​render-after * purchase.​thank-you.​chat.​render * purchase.​thank-you.​customer-information.​render-after * purchase.​thank-you.​footer.​render-after * purchase.​thank-you.​header.​render-after ## StandardApi The base API object provided to `purchase` extension targets. * **settings** **StatefulRemoteSubscribable\** **required** The settings matching the settings definition written in the [`shopify.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) file. Refer to [settings examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/settings#examples) for more information. **Note:** When an extension is being installed in the editor, the settings will be empty until a merchant sets a value. In that case, this object will be updated in real time as a merchant fills in the settings. ### ExtensionSettings The merchant-defined setting values for the extension. ## use​Settings() Returns the setting values defined by the merchant for the extension. ### Returns * **Partial\** Examples ### Examples * #### Accessing merchant settings ##### Description You can retrieve settings values within your extension. In React, the \`useSettings()\` hook re-renders your extension with the latest values. In JavaScript, subscribe to changes and update your UI directly. ##### React ```jsx import { reactExtension, Banner, useSettings, } from '@shopify/ui-extensions-react/checkout'; export default reactExtension( 'purchase.checkout.block.render', () => , ); function Extension() { const {banner_title} = useSettings(); return ; } ``` ##### JavaScript ```js import { extension, Banner, } from '@shopify/ui-extensions/checkout'; export default extension( 'purchase.checkout.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/checkout-ui-extensions/configuration#settings-definition) for more information on how to define these. ##### shopify.extension.toml ```toml api_version = "2023-07" [[extensions]] name = "My checkout extension" handle = "checkout-ui" type = "ui_extension" [[extensions.targeting]] target = "purchase.checkout.block.render" module = "./Checkout.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" ``` ## Related [Reference - Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets) [Reference - Components](https://shopify.dev/docs/api/checkout-ui-extensions/components) [Reference - Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) [Learn - Tutorials](https://shopify.dev/apps/checkout)