Choose a version:

Localized Fields

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 <[]>: 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.

SubscribableSignalLike

Represents a read-only value managed on the main thread that an extension can subscribe to. Example: Checkout uses this to manage the state of an object and communicate state changes to extensions running in a sandboxed web worker. This interface is compatible with [Preact's ReadonlySignal](https://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709). Some fields are deprecated but still supported for backwards compatibility. In version 2025-10, [`StatefulRemoteSubscribable`](https://github.com/Shopify/remote-dom/blob/03929aa8418a89d41d294005f219837582718df8/packages/async-subscription/src/types.ts#L17) was replaced with `ReadonlySignalLike`. Checkout will remove the old fields some time in the future.

current
```
T
```
destroy
```
() => Promise<void>
```
subscribe
```
(fn: (value: T) => void) => () => void
```
value
```
T
```

export interface SubscribableSignalLike<T> extends ReadonlySignalLike<T> {
  /**
   * @deprecated Use `.value` instead.
   */
  readonly current: T;
  /**
   * @deprecated No longer needed. Use Preact Signal management instead.
   */
  destroy(): Promise<void>;
}

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'

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

Anchor to useLocalizedField
useLocalizedField(
key
)

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

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

Examples

Preact

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

Read localized fields

Preact

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