---
title: Localized Fields
description: The API for interacting with localized fields.
api_version: 2025-04
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2025-04/apis/localized-fields
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2025-04/apis/localized-fields.md
---

# Localized Fields

Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) for some properties.

The API for interacting with localized fields.

## StandardApi

The base API object provided to `purchase` extension targets.

* localizedFields

  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

  ```ts
  LocalizedFieldKey
  ```

* title

  ```ts
  string
  ```

* value

  ```ts
  string
  ```

```ts
export interface LocalizedField {
  key: LocalizedFieldKey;
  title: string;
  value: 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'
```

## use​Localized​Fields([keys](#uselocalizedfields-propertydetail-keys)​)

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

### Parameters

* keys

  LocalizedFieldKey\[]

### Returns

* LocalizedField\[]

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

### LocalizedField

* key

  ```ts
  LocalizedFieldKey
  ```

* title

  ```ts
  string
  ```

* value

  ```ts
  string
  ```

```ts
export interface LocalizedField {
  key: LocalizedFieldKey;
  title: string;
  value: string;
}
```

## use​Localized​Field([key](#uselocalizedfield-propertydetail-key)​)

Returns the requested localized field and re-renders your component if the value changes.

### Parameters

* key

  LocalizedFieldKey

  required

### Returns

* LocalizedField | undefined

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

### LocalizedField

* key

  ```ts
  LocalizedFieldKey
  ```

* title

  ```ts
  string
  ```

* value

  ```ts
  string
  ```

```ts
export interface LocalizedField {
  key: LocalizedFieldKey;
  title: string;
  value: string;
}
```

Examples

### Examples

* #### Read localized fields

  ##### React

  ```jsx
  import {
    reactExtension,
    useBuyerJourneyIntercept,
    useLocalizedField,
  } from '@shopify/ui-extensions-react/checkout';

  // 1. Choose an extension target
  export default reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

  function Extension() {
    // 2. Access localized field value
    const taxIdField = useLocalizedField(
      'TAX_CREDENTIAL_BR',
    );

    // 3. 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',
            };
      },
    );
  }
  ```

  ##### JavaScript

  ```js
  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 value
          taxIdField = localizedFields?.find(
            ({key}) => key === 'TAX_CREDENTIAL_BR',
          );
        },
      );

      // 3. Validate localized field value
      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',
              };
        },
      );
    },
  );
  ```

## Related

[Reference - Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)

[Reference - Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)

[Reference - Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)

[Learn - Tutorials](https://shopify.dev/apps/checkout)