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.

Docs_Standard_LocalizedFieldsApi

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.
```
StatefulRemoteSubscribable<LocalizedField[]>
```

export interface Docs_Standard_LocalizedFieldsApi
  extends Pick<StandardApi, 'localizedFields'> {}

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'

Was this section helpful?

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

[]

UseLocalizedFieldsGeneratedType

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

keys
```
LocalizedFieldKey[]
```

LocalizedField[]

LocalizedField[]

export function useLocalizedFields<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(keys?: LocalizedFieldKey[]): LocalizedField[] {
  const {localizedFields} = useApi<Target>();

  if (!localizedFields) {
    throw new ScopeNotGrantedError(
      'Using localized fields requires having personal customer data permissions granted to your app.',
    );
  }

  const localizedFieldsData = useSubscription(localizedFields);

  if (!keys) {
    return localizedFieldsData;
  }

  if (!keys.length) {
    return [];
  }

  return localizedFieldsData.filter(({key}) => keys.includes(key));
}

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

Was this section helpful?

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

UseLocalizedFieldGeneratedType

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

key
```
LocalizedFieldKey
```

LocalizedField | undefined

LocalizedField | undefined

export function useLocalizedField<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(key: LocalizedFieldKey): LocalizedField | undefined {
  const fields = useLocalizedFields<Target>([key]);
  return fields[0];
}

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

Was this section helpful?

Read localized fields

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',

};

);

}

examples

Read localized fields

React

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

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