Skip to main content

Add locally required data to orders using localized fields

Localized fields are additional fields that are required under certain circumstances, depending on the shop country, destination country, and origin countries for all the merchandise in the cart. For example, some countries require additional fields for customs information or tax identification numbers. You can retrieve the information from these fields using the LocalizedFieldConnection connection.

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

Anchor to RequirementsRequirements

Anchor to Step 1: Add a country fieldStep 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.

Note

In this step, you'll use a Brazilian CPF number. Visit the help docs to view the complete list of country fields that can be collected.

Anchor to Add a country field to a draft orderAdd a country field to a draft order

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

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

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation draftOrderCreate($input: DraftOrderInput!) {
draftOrderCreate(input: $input) {
draftOrder {
id
localizedFields(first:1) {
edges {
node {
key
value
}
}
}
}
}
}

Variables

{
"input": {
"lineItems": {
"variantId": "gid://shopify/ProductVariant/38615082242",
"quantity": 1
},
"localizedFields": {
"key": "TAX_CREDENTIAL_BR",
"value": "39053344705"
},
"email": "john_sally@gmail.com"
}
}

JSON response

{
"data": {
"draftOrderCreate": {
"draftOrder": {
"id": "gid://shopify/DraftOrder/243906019384",
"localizedFields": {
"edges": [
{
"node": {
"key": "TAX_CREDENTIAL_BR",
"value": "39053344705"
}
}
]
}
}
}
}
}

Anchor to Convert the draft order into an orderConvert 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation draftOrderComplete($id: ID!) {
draftOrderComplete(id: $id) {
draftOrder {
id
order {
id
}
}
}
}

Variables

{
"id": "gid://shopify/DraftOrder/243906019384"
}

JSON response

{
"data": {
"draftOrderComplete": {
"draftOrder": {
"id": "gid://shopify/DraftOrder/243906019384"
},
"order": {
"id":"gid://shopify/Order/1"
},
}
}
}

Anchor to Add a country field to an existing orderAdd a country field to an existing order

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

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

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation orderUpdate($input: OrderInput!) {
orderUpdate(input: $input) {
order {
id
localizedFields(first: 1) {
edges {
node {
key
value
}
}
}
}
}
}

Variables

{
"input": {
"id": "gid://shopify/Order/5464858562",
"localizedFields": {
"key": "TAX_CREDENTIAL_BR",
"value": "39053344705"
}
}
}

JSON response

{
"data": {
"orderUpdate": {
"order": {
"id": "gid://shopify/Order/5464858562",
"localizedFields": {
"edges": [
{
"node": {
"key": "TAX_CREDENTIAL_BR",
"value": "39053344705"
}
}
]
}
}
}
}
}

Anchor to Collect a country field on checkoutCollect a country field on checkout

Note

To test this feature, you need an order containing a localized field that was collected during checkout. You can create a localized field using a developer preview store.

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.

  1. Set the address of your store to Brazil. Remember to change your address back when you've completed the tutorial.

  2. From your storefront, add a product to your cart and then complete a checkout.

  3. Enter a valid Brazilian CPF number into the new CPF/CNPJ localized field in the Additional information section. If you don’t have one, then you can use 39053344705.

  4. Complete the checkout.

  5. 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.

Anchor to Step 2: Retrieve the country fieldStep 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 localizedFields connection. Check the response to make sure that the CPF/CNPJ field is returned.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
order(id: "gid://shopify/Order/1") {
id
localizedFields(first: 5) {
edges {
node {
countryCode
purpose
title
value
}
}
}
}
}

JSON response

{
"data": {
"order": {
"id": "gid://shopify/Order/1",
"localizedFields": {
"edges": [
{
"node": {
"countryCode": "BR",
"purpose": "TAX",
"title": "CPF/CNPJ",
"value": "39053344705"
}
}
]
}
}
}
}

Anchor to Validate a country fieldValidate a country field

You can use a checkout UI extension or Shopify Function to implement custom validation for the localized field. Learn more about building custom validation for checkout in the following tutorials:

Anchor to Next stepsNext steps

Was this page helpful?