All Tutorials

Get a tax ID using localization extensions

All Tutorials

Get a tax ID using localization extensions

Get a tax ID using localization extensions

This guide explains how to use the GraphQL Admin API to return a tax ID collected during checkout. Localization extensions will be introduced in the 2020-07 API version and can be tested with a Localization Extensions developer preview store.

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 new localizationExtensions connection on the Order object.

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

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.

Collect a tax ID 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 with the Localization extensions preview enabled.

For this tutorial, you'll set the address of your shop to Brazil (since Brazilian merchants are required to collect a tax ID for government invoicing) and then 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 tax ID 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
        }
      }
    }
  }
}

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.