Choose a version:

Localized Fields API

Requires access to protected customer data for some properties.

The Localized Fields API provides access to country-specific checkout fields, such as tax credentials and regional identifiers. Use this API to display localized field values, validate them before the buyer proceeds, and surface field-specific error messages.

Localized fields are available only when the merchant has configured them for the buyer's country. useLocalizedField returns undefined when no field is configured. The set of available fields varies by country and Shopify's regional requirements. Extensions can't add custom localized fields.

Anchor to Use casesUse cases

Validate localized fields: Check that country-specific fields like tax IDs meet length or format requirements before the buyer proceeds.
Display country-specific values: Show the current value of a localized field or use it in checkout calculations.
Display field-specific errors: Surface validation errors directly underneath the relevant localized field to guide the buyer.

Support

Targets (31)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides localized field data for the current checkout. Access the following properties on shopify to read country-specific checkout fields. Available to purchase extension targets.

Anchor to localizedFields localizedFields <[]>: Additional region-specific fields required during checkout, such as tax identification numbers (Brazil's CPF/CNPJ) or customs credentials. The property is available only if the extension has access to protected customer data. The array is empty if the current checkout doesn't require any localized fields.

SubscribableSignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends `ReadonlySignalLike` with deprecated fields that are still supported for backwards compatibility.

current
The current value of the signal. Equivalent to `.value`, accessing this property subscribes to changes when used in a reactive context.
```
T
```
destroy
Cleans up the subscription and releases any resources held by this signal. After calling `destroy()`, the signal stops receiving updates from the main thread.
```
() => Promise<void>
```
subscribe
Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.
```
(fn: (value: T) => void) => () => void
```
value
The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.
```
T
```

LocalizedField

key
The identifier for the localized field, indicating the type of information collected (for example, a tax credential or shipping credential for a specific country).
```
LocalizedFieldKey
```
title
The localized display label for the field, suitable for rendering in the UI.
```
string
```
value
The current value entered by the buyer for this field.
```
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 Available Preact hooksAvailable Preact hooks

The following Preact hooks provide a convenience wrapper that makes it easier to perform common tasks without writing your own logic.

Anchor to useLocalizedFields
useLocalizedFields(
keys
)

The useLocalizedFields hook returns the current localized fields and re-renders your component when the values change. Pass an optional array of keys to filter the results.

Anchor to useLocalizedFields-parametersParameters

Anchor to keys keys []

Anchor to useLocalizedFields-returnsReturns

[]

Anchor to useLocalizedField
useLocalizedField(
key
)

The useLocalizedField hook returns a single localized field for the specified key, or undefined if the field isn't available. Re-renders your component when the value changes.

Anchor to useLocalizedField-parametersParameters

Anchor to key key required

Anchor to useLocalizedField-returnsReturns

| undefined

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

import {

useBuyerJourneyIntercept,

useLocalizedField,

} from '@shopify/ui-extensions/checkout/preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

// 1. Access localized field

const taxIdField = useLocalizedField(

'TAX_CREDENTIAL_BR',

);

// 2. 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',

};

);

}

Examples

Description

Enforce format requirements on a country-specific tax credential before the buyer proceeds. This example uses `useLocalizedField` to target the Brazilian tax ID field and `useBuyerJourneyIntercept` to block progress when the value is missing or exceeds the character limit.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

import {
  useBuyerJourneyIntercept,
  useLocalizedField,
} from '@shopify/ui-extensions/checkout/preact';

export default function extension() {
  render(<Extension />, document.body);
}

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

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

Description

Read a country-specific checkout field and display its value to the buyer. This example accesses the Brazilian tax ID field through `shopify.localizedFields` and renders it when present.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  const localizedFields =
    shopify.localizedFields?.value;

  const taxField = localizedFields?.find(
    (field) => field.key === 'TAX_CREDENTIAL_BR',
  );

  if (!taxField?.value) return null;

  return (
    <s-text>
      {taxField.title}: {taxField.value}
    </s-text>
  );
}

Anchor to Best practicesBest practices

Use the field's title in error messages: The title property provides the localized, human-readable name of the field. Include it in validation errors so the buyer understands which field needs attention.
Check field availability before accessing values: Localized fields depend on the buyer's country. Always verify that useLocalizedField returns a value before accessing its properties.

Was this page helpful?

Anchor to Use casesUse cases

Supported targets

Supported targets

Anchor to PropertiesProperties

SubscribableSignalLike

LocalizedField

LocalizedFieldKey

Anchor to Available Preact hooksAvailable Preact hooks

Anchor to useLocalizedFieldsuseLocalizedFields(keyskeys)

Anchor to useLocalizedFields-parametersParameters

Anchor to useLocalizedFields-returnsReturns

Anchor to useLocalizedFielduseLocalizedField(keykey)

Anchor to useLocalizedField-parametersParameters

Anchor to useLocalizedField-returnsReturns

Anchor to Best practicesBest practices

Anchor to useLocalizedFields
useLocalizedFields(
keys
)

Anchor to useLocalizedField
useLocalizedField(
key
)