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

# Localized Fields API

**Requires access to \[protected customer data]\(/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
  ```

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

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

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

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

Examples

### Examples

* #### Read localized fields

  ##### React

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

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

## 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)