--- title: Localized Fields API description: >- Access country-specific checkout fields like tax IDs and postal codes. Requires protected customer data access for some properties. 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 Localized Fields API provides access to country-specific checkout fields, such as tax credentials and regional identifiers. Use this API to display localized field values, validate them before the buyer proceeds, and surface field-specific error messages. Localized fields are available only when the merchant has configured them for the buyer's country. `useLocalizedField` returns `undefined` when no field is configured. The set of available fields varies by country and Shopify's regional requirements. Extensions can't add custom localized fields. ### Use cases * **Validate localized fields**: Check that country-specific fields like tax IDs meet length or format requirements before the buyer proceeds. * **Display country-specific values**: Show the current value of a localized field or use it in checkout calculations. * **Display field-specific errors**: Surface validation errors directly underneath the relevant localized field to guide the buyer. ### Support Targets (31) ### Supported targets * [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target) * [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target) * [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets) * [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-) * purchase.​checkout.​chat.​render * [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target) * [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-) * [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets) * [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target) * [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target) * [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-) * [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets) * [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-) * [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets) * [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target) * [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-) * [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets) * [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-) * [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets) * [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets) * [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-) * [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-) * [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets) * [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-) * [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target) * [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets) * [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-) * purchase.​thank-you.​chat.​render * [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target) * [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target) * [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target) ### Properties The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides localized field data for the current checkout. Access the following properties on `shopify` to read country-specific checkout fields. Available 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' ``` ### Available Preact hooks The following Preact hooks provide a convenience wrapper that makes it easier to perform common tasks without writing your own logic. ## use​Localized​Fields(**[keys](#uselocalizedfieldsgeneratedtype-propertydetail-keys)**​) The `useLocalizedFields` hook returns the current localized fields and re-renders your component when the values change. Pass an optional array of keys to filter the results. ### Parameters * **keys** **LocalizedFieldKey\[]** ### Returns * **LocalizedField\[]** ## use​Localized​Field(**[key](#uselocalizedfieldgeneratedtype-propertydetail-key)**​) The `useLocalizedField` hook returns a single localized field for the specified key, or `undefined` if the field isn't available. Re-renders your component when the value changes. ### Parameters * **key** **LocalizedFieldKey** **required** ### Returns * **LocalizedField | undefined** Examples ### Examples * #### ##### Description Enforce format requirements on a country-specific tax credential before the buyer proceeds. This example uses \`useLocalizedField\` to target the Brazilian tax ID field and \`useBuyerJourneyIntercept\` to block progress when the value is missing or exceeds the character limit. ##### jsx ```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', }; }, ); } ``` * #### ##### Description Read a country-specific checkout field and display its value to the buyer. This example accesses the Brazilian tax ID field through \`shopify.localizedFields\` and renders it when present. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { const localizedFields = shopify.localizedFields?.value; const taxField = localizedFields?.find( (field) => field.key === 'TAX_CREDENTIAL_BR', ); if (!taxField?.value) return null; return ( {taxField.title}: {taxField.value} ); } ``` *** ## Best practices * **Use the field's `title` in error messages**: The `title` property provides the localized, human-readable name of the field. Include it in validation errors so the buyer understands which field needs attention. * **Check field availability before accessing values**: Localized fields depend on the buyer's country. Always verify that `useLocalizedField` returns a value before accessing its properties. ***