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 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 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.
Using the id value from the response of draftOrderCreate, call the draftOrderComplete mutation to convert the DraftOrder to an Order.
Add a country field to an existing order using the GraphQL Admin API
To add a country field to an existing Order using the GraphQL Admin API, pass the LocalizationExtensionsInput object to the orderUpdate mutation.
The following mutation updates an existing order with a Brazilian CPF number. Record the order id from the response for the next step.
Collect a country field on checkout
To test this feature, you need an order containing a localization extension field that was collected during checkout. You can create a localization extension field using a developer preview store.
To begin, set the address of your shop 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 shop 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/CNPJvalue is displayed inside the Customer card, in the Additional information section.
Get the country field for an order
Pass the order GID 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.
Additional information
For additional information on editing orders, refer to the GraphQL Admin API reference.