Add locally required data to orders using localization extensions

Localization extensions are additional fields that are 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 LocalizationExtensionConnection connection.

This guide shows how to create and query country fields using the GraphQL Admin API.

Requirements

Anchor link to section titled "Requirements"

Your app can make authenticated requests to the GraphQL Admin API.
Your app has the read_orders access scope. Learn how to configure your access scopes using Shopify CLI.
You've created at least one draft order and order in your Shopify store.

Step 1: Add a country field

Anchor link to section titled "Step 1: Add a country field"

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

Add a country field to a draft order

Anchor link to section titled "Add a country field to a draft order"

To add a country field to a DraftOrder, pass the LocalizationExtensionsInput object to the draftOrderCreate mutation.

The following mutation creates a draft order with a Brazilian CPF number:

Convert the draft order into an order

Anchor link to section titled "Convert the draft order into an order"

Using the id value from the response of the draftOrderCreate mutation, use the draftOrderComplete mutation to convert the draft order into an order.

Add a country field to an existing order

Anchor link to section titled "Add a country field to an existing order"

To add a country field to an existing order, pass the LocalizationExtensionInput input object to the orderUpdate mutation.

The following mutation updates an existing order with a Brazilian CPF number:

Collect a country field on checkout

Anchor link to section titled "Collect a country field on checkout"

To collect a country field on checkout, you can set the address of your store to Brazil (since Brazilian merchants are required to collect a tax ID for government invoicing) and complete a checkout from your storefront.

Set the address of your store to Brazil. Remember to change your address back when you've completed the tutorial.
From your storefront, add a product to your cart and then complete a checkout.
Enter a valid Brazilian CPF number into the new CPF/CNPJ localization extension field in the Additional information section. If you don’t have one, then you can use 39053344705.
Complete the checkout.
Open the order in the Shopify admin and verify that the CPF/CNPJ value is displayed inside the customer card, in the Additional information section.

Step 2: Retrieve the country field

Anchor link to section titled "Step 2: Retrieve the country field"

To retrieve a country field for an order, you can use the order query. Pass the order ID to the order query and request the first five entries of the localizationExtensions connection. Check the response to make sure that the CPF/CNPJ field is returned.

Next steps

Anchor link to section titled "Next steps"

Use the GraphQL Admin API to translate an online store's content.
Use the Storefront API to retrieve translated content.
Explore an example for retrieving a list of shop locales with the GraphQL Admin API.
Explore examples for retrieving translatable resources with the GraphQL Admin API.
Learn how to support multiple currencies and languages in your theme.