Manage country fields using localization extensions

Localization extensions are additional fields required by certain countries on international orders. For example, some countries require additional fields for customs information or tax identification numbers. You can retrieve the information from these fields using the localizationExtensions connection on the Order object.

Refer to the GraphQL Admin API reference for more information on order and localization extensions objects.

This tutorial explains how to create and query country fields using the GraphQL Admin API. For this tutorial, you'll be using a Brazilian CPF number, but the following country fields can also be collected:

  • South Korea: Personal Customs Code
  • China: Resident ID number
  • Italy: Codice Fiscale and PEC

Access scopes

To use the GraphQL Admin API to access the information collected in checkout, your app needs to request the read_order access scope for a Shopify store. For more information on requesting access scopes when your app is installed, see OAuth.

Add a country field to an order

You can add a country field to an order using the GraphQL Admin API or you can collect it on checkout.

Add a country field to a draft order using the GraphQL Admin API

To add a country field to a draft order using the GraphQL Admin API, pass the LocalizationExtensionsInput object to the draftOrderCreate mutation.

The following mutation creates a draft order with a Brazilian CPF number. Record the draft order id from the response for the next step.

View response

Using the id value from the response of draftOrderCreate, call the draftOrderComplete mutation to convert the