Migrate to Polaris
Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.
Localized Fields API
Requires access to protected customer data for some properties.
Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data) for some properties.:
The API for interacting with localized fields.
Anchor to standardapiStandardApi
The base API object provided to purchase extension targets.
- Anchor to localizedFieldslocalizedFieldslocalizedFieldsStatefulRemoteSubscribable<LocalizedField[]>StatefulRemoteSubscribable<LocalizedField[]>
The API for reading additional fields that are required in checkout under certain circumstances. For example, some countries require additional fields for customs information or tax identification numbers.
LocalizedField
- key
LocalizedFieldKey - title
string - value
string
LocalizedFieldKey
A union of keys for the localized fields that are required by certain countries.
'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'Returns the current localized fields and re-renders your component if the values change.
Anchor to useLocalizedFields-parametersParameters
- Anchor to keyskeyskeysLocalizedFieldKey[]LocalizedFieldKey[]
LocalizedField[]LocalizedField[]
LocalizedFieldKey
A union of keys for the localized fields that are required by certain countries.
'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'LocalizedField
- key
LocalizedFieldKey - title
string - value
string
Returns the current localized fields and re-renders your component if the values change.
Anchor to useLocalizedField-parametersParameters
- Anchor to keykeykeyLocalizedFieldKeyLocalizedFieldKeyrequiredrequired
LocalizedField | undefinedLocalizedField | undefined
LocalizedFieldKey
A union of keys for the localized fields that are required by certain countries.
'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'LocalizedField
- key
LocalizedFieldKey - title
string - value
string
Examples
import {
reactExtension,
useBuyerJourneyIntercept,
useLocalizedFields,
} from '@shopify/ui-extensions-react/checkout';
export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);
function Extension() {
// 1. Access localized field values
const localizedFields = useLocalizedFields([
'TAX_CREDENTIAL_BR',
]);
// 2. Access localized field values
const taxIdField = localizedFields?.[0];
// 3. Validate localized field values
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',
};
},
);
}
Examples
Read localized fields
React
import { reactExtension, useBuyerJourneyIntercept, useLocalizedFields, } from '@shopify/ui-extensions-react/checkout'; export default reactExtension( 'purchase.checkout.block.render', () => <Extension />, ); function Extension() { // 1. Access localized field values const localizedFields = useLocalizedFields([ 'TAX_CREDENTIAL_BR', ]); // 2. Access localized field values const taxIdField = localizedFields?.[0]; // 3. Validate localized field values 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', }; }, ); }JavaScript
import {extension} from '@shopify/ui-extensions/checkout'; // 1. Choose an extension target export default extension( 'purchase.checkout.block.render', (root, {buyerJourney, localizedFields}) => { let taxIdField; localizedFields?.subscribe( (localizedFields) => { // 2. Access localized field values taxIdField = localizedFields?.find( ({key}) => key.startsWith('TAX_CREDENTIAL'), ); }, ); // 3. Validate localized field values buyerJourney.intercept( ({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', }; }, ); }, );
Was this page helpful?