Choose a version:

Localized Fields
API

Requires access to 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 localizedFields localizedFields StatefulRemoteSubscribable<[]>: 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'

Was this section helpful?

Anchor to useLocalizedFields
useLocalizedFields(
keys
)

Returns the current localized fields and re-renders your component if the values change.

Anchor to useLocalizedFields-parametersParameters

Anchor to keys keys []

Anchor to useLocalizedFields-returnsReturns

[]

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;
}

Was this section helpful?

Anchor to useLocalizedField
useLocalizedField(
key
)

Returns the current localized fields and re-renders your component if the values change.

Anchor to useLocalizedField-parametersParameters

Anchor to key key required

Anchor to useLocalizedField-returnsReturns

| 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;
}

Was this section helpful?

Read localized fields

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',
            };
      },
    );
  },
);