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.

Mutation:

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

Input:

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

View response

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

Using the id value from the response of draftOrderCreate, call the draftOrderComplete mutation to convert the DraftOrder to an Order.

Mutation:

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

Input:

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

View response

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

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.

Mutation:

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

Input:

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

View response

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

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:

1. Set the address of your shop 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 localization extension 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.

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.

Query:

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

View response

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

Additional information

For additional information on editing orders, refer to the GraphQL Admin API reference.