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.

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
```

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'

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

[]

Anchor to useLocalizedField
useLocalizedField(
key
)

Returns the current localized field or undefined for the specified localized field key and re-renders your component if the value changes.

Anchor to useLocalizedField-parametersParameters

Anchor to key key required

Anchor to useLocalizedField-returnsReturns

| undefined

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