--- title: Localized Fields API description: The API for interacting with localized fields. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/localized-fields-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/localized-fields-api.md --- # Localized Fields API **Requires access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data) for some properties.:** The API for interacting with localized fields. ### Support Targets (31) ### Supported targets * 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. * **localizedFields** **SubscribableSignalLike\** Additional region-specific fields required during checkout, such as tax identification numbers (Brazil's CPF/CNPJ) or customs credentials. The property is available only if the extension has access to protected customer data. The array is empty if the current checkout doesn't require any localized fields. ### 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 ``` ### LocalizedField * key The identifier for the localized field, indicating the type of information collected (for example, a tax credential or shipping credential for a specific country). ```ts LocalizedFieldKey ``` * title The localized display label for the field, suitable for rendering in the UI. ```ts string ``` * value The current value entered by the buyer for this field. ```ts string ``` ### LocalizedFieldKey A union of keys for the localized fields that are required by certain countries. ```ts 'SHIPPING_CREDENTIAL_BR' | 'SHIPPING_CREDENTIAL_CL' | 'SHIPPING_CREDENTIAL_CN' | 'SHIPPING_CREDENTIAL_CO' | 'SHIPPING_CREDENTIAL_CR' | 'SHIPPING_CREDENTIAL_EC' | 'SHIPPING_CREDENTIAL_ES' | 'SHIPPING_CREDENTIAL_GT' | 'SHIPPING_CREDENTIAL_ID' | 'SHIPPING_CREDENTIAL_KR' | 'SHIPPING_CREDENTIAL_MY' | 'SHIPPING_CREDENTIAL_MX' | 'SHIPPING_CREDENTIAL_PE' | 'SHIPPING_CREDENTIAL_PT' | 'SHIPPING_CREDENTIAL_PY' | 'SHIPPING_CREDENTIAL_TR' | 'SHIPPING_CREDENTIAL_TW' | 'SHIPPING_CREDENTIAL_TYPE_CO' | 'TAX_CREDENTIAL_BR' | 'TAX_CREDENTIAL_CL' | 'TAX_CREDENTIAL_CO' | 'TAX_CREDENTIAL_CR' | 'TAX_CREDENTIAL_EC' | 'TAX_CREDENTIAL_ES' | 'TAX_CREDENTIAL_GT' | 'TAX_CREDENTIAL_ID' | 'TAX_CREDENTIAL_IT' | 'TAX_CREDENTIAL_MX' | 'TAX_CREDENTIAL_MY' | 'TAX_CREDENTIAL_PE' | 'TAX_CREDENTIAL_PT' | 'TAX_CREDENTIAL_PY' | 'TAX_CREDENTIAL_TR' | 'TAX_CREDENTIAL_TYPE_CO' | 'TAX_CREDENTIAL_TYPE_MX' | 'TAX_CREDENTIAL_USE_MX' | 'TAX_EMAIL_IT' ``` ## use​Localized​Fields(**[keys](#uselocalizedfields-propertydetail-keys)**​) Returns the current localized fields and re-renders your component if the values change. ### Parameters * **keys** **LocalizedFieldKey\[]** ### Returns * **LocalizedField\[]** ## use​Localized​Field(**[key](#uselocalizedfield-propertydetail-key)**​) Returns the requested localized field and re-renders your component if the value changes. ### Parameters * **key** **LocalizedFieldKey** **required** ### Returns * **LocalizedField | undefined** Examples ### Examples * #### Read localized fields ##### Preact ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import { useBuyerJourneyIntercept, useLocalizedField, } from '@shopify/ui-extensions/checkout/preact'; export default function extension() { render(, document.body); } function Extension() { // 1. Access localized field const taxIdField = useLocalizedField( 'TAX_CREDENTIAL_BR', ); // 2. Validate localized field value useBuyerJourneyIntercept( ({canBlockProgress}) => { return canBlockProgress && taxIdField && (!taxIdField.value || taxIdField.value.length > 10) ? { behavior: 'block', reason: 'Invalid tax ID', errors: [ { message: `${taxIdField.title} is required and cannot exceed 10 characters in length`, // Show an error under the field target: `$.cart.localizedField.${taxIdField.key}`, }, ], } : { behavior: 'allow', }; }, ); } ``` ## 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)