Localized Fields
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
export interface 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
export interface 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
export interface 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?