Shopify Admin API Now Exposes Customer Tax Settings: A Deep Dive for Developers

Shopify is continuously evolving to meet the complex needs of global commerce. One of the most significant recent updates for developers is the public accessibility of customer tax settings via the Admin GraphQL API. This new capability, available in API version 2026-07, allows applications to query a customer's tax identifier, such as a VAT number, directly through the API. This is a game-changer for apps and services focused on tax compliance, reporting, and providing specialized services to merchants operating in diverse tax jurisdictions.

What's New and Why It Matters

Previously, accessing granular customer tax information programmatically was challenging, often requiring manual intervention or complex workarounds. This new feature directly addresses that gap. By enabling developers to query Customer.taxSettings.taxId, Shopify empowers apps to:

Enhance Tax Compliance: Automatically verify and apply correct tax rates based on customer tax IDs, ensuring merchants adhere to local and international tax regulations.
Streamline Reporting: Facilitate more accurate and automated tax reporting by providing direct access to essential customer tax data.
Improve Customer Experience: Offer smoother checkout processes for B2B customers or those in regions with specific tax requirements, by automatically handling tax-exempt status or applicable tax IDs.
Build Advanced Features: Develop sophisticated tools for tax management, auditing, and financial reconciliation that rely on precise customer tax data.

The requirement for read_customers or read_taxes access scopes ensures that data access is controlled and adheres to Shopify's privacy and security standards. This update is particularly impactful for merchants selling across borders or operating in industries with strict tax obligations.

Technical Explanation: Accessing Customer Tax Data via GraphQL

The core of this update lies in the expansion of the Shopify Admin GraphQL API schema. The Customer object now includes a nested taxSettings object, which in turn contains the taxId field. This field represents the unique tax identifier associated with a customer, such as a Value Added Tax (VAT) identification number, Goods and Services Tax (GST) number, or similar regional tax registration numbers.

To retrieve this information, you'll need to construct a GraphQL query that selects the customer and specifies the fields you wish to retrieve. The query structure will look something like this:

query GetCustomerTaxId($customerId: ID!) {
  customer(id: $customerId) {
    id
    firstName
    lastName
    email
    taxSettings {
      taxId
    }
  }
}

In this query:

query GetCustomerTaxId($customerId: ID!): Defines a query operation named GetCustomerTaxId that accepts a variable $customerId of type ID! (non-nullable ID).
customer(id: $customerId): Specifies that we want to query for a single customer, using the provided $customerId.
id, firstName, lastName, email: These are standard customer fields that you might want to retrieve alongside the tax information for context.
taxSettings { taxId }: This is the crucial part. It navigates into the taxSettings object and retrieves the taxId field.

When executing this query, ensure your application has been granted the necessary access scopes (read_customers or read_taxes) by the merchant. The response will contain the customer's tax ID if it's set, or it will be null if no tax ID is configured for that customer.

Step-by-Step Implementation Guide

Integrating this new capability into your application involves a few key steps:

1. Obtain Necessary Scopes

When installing your app or requesting access from a merchant, ensure you include the read_customers or read_taxes scope in your OAuth request. This grants your app the permission to read customer data, including tax settings.

2. Identify the Customer

You'll need a way to identify the specific customer whose tax information you want to retrieve. This could be via their customer ID (e.g., `gid://shopify/Customer/1234567890`), email address, or another unique identifier that you can use to fetch the customer object.

3. Construct and Execute the GraphQL Query

Using a GraphQL client (like Apollo Client, `fetch` API in JavaScript, or a server-side HTTP client), send the query defined above to the Shopify Admin GraphQL API endpoint. Remember to pass the customer ID as a variable.

4. Process the Response

Parse the JSON response from the API. Check if customer.taxSettings.taxId contains a value. Handle cases where the tax ID might be null or absent.

5. Utilize the Data

Based on the retrieved tax ID, implement your application's logic. This could involve:

Displaying the tax ID to the merchant in your app's dashboard.
Using the tax ID to determine applicable tax rates for a specific order or customer group.
Validating the tax ID against external tax authorities (if your app provides such a service).

Working Code Examples

GraphQL Query Example

This is the basic GraphQL query structure you would use:

query GetCustomerTaxSettings($customerId: ID!) {
  customer(id: $customerId) {
    id
    email
    taxSettings {
      taxId
    }
  }
}

JavaScript Example (using `fetch` API)

This example demonstrates how to make the GraphQL request from a Node.js backend or a Shopify App Bridge-enabled frontend.

async function getCustomerTaxId(customerId, shopifyAccessToken) {
  const shopifyApiEndpoint = `https://YOUR_SHOP_NAME.myshopify.com/admin/api/2026-07/graphql.json`;

  const query = `
    query GetCustomerTaxSettings($customerId: ID!) {
      customer(id: $customerId) {
        id
        email
        taxSettings {
          taxId
        }
      }
    }
  `;

  const variables = {
    customerId: customerId // e.g., 'gid://shopify/Customer/1234567890'
  };

  try {
    const response = await fetch(shopifyApiEndpoint, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Shopify-Access-Token': shopifyAccessToken
      },
      body: JSON.stringify({ query, variables })
    });

    if (!response.ok) {
      const errorData = await response.json();
      console.error('Shopify API Error:', errorData);
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();

    if (data.errors) {
      console.error('GraphQL Errors:', data.errors);
      throw new Error('GraphQL query returned errors.');
    }

    const taxId = data.data.customer?.taxSettings?.taxId;
    console.log(`Customer ${customerId} tax ID:`, taxId);
    return taxId;

  } catch (error) {
    console.error('Failed to fetch customer tax ID:', error);
    return null;
  }
}

// Example usage:
// const customerId = 'gid://shopify/Customer/1234567890'; // Replace with actual customer GID
// const shopifyAccessToken = 'YOUR_ADMIN_API_ACCESS_TOKEN'; // Replace with your app's access token
// getCustomerTaxId(customerId, shopifyAccessToken).then(taxId => {
//   if (taxId) {
//     console.log('Successfully retrieved tax ID:', taxId);
//   } else {
//     console.log('Could not retrieve tax ID or customer has no tax ID set.');
//   }
// });

Liquid Example (for themes or custom apps using Liquid)

While direct GraphQL calls are typically made server-side or via JavaScript, you can leverage this data if it's already fetched and made available to your Liquid template. For example, if you have a custom app that fetches this data and passes it to the theme context:

Note: Direct GraphQL queries are not possible within standard Liquid. This assumes the data has been pre-fetched and exposed to Liquid.

{% comment %}
This is a conceptual example. In a real scenario, the 'customer_tax_id' variable
would need to be set in the controller or backend of your custom app
and passed into the Liquid context.
{% endcomment %}

{% if customer.taxSettings.taxId %}
  Your Tax ID: {{ customer.taxSettings.taxId }}
  Please ensure this is correct for tax purposes.
{% else %}
  No tax ID found for your account. Please contact support if you believe this is an error.
{% endif %}

Real-World Use Case: A B2B Wholesale App

Consider a Shopify app designed for B2B wholesale businesses. These businesses often operate in different countries and need to handle VAT, GST, and other regional taxes correctly. They may be tax-exempt in certain jurisdictions or require specific tax IDs for their customers.

Scenario: A wholesale merchant uses your app to manage their B2B customers. When a customer logs in or places an order, the app needs to:

Automatically apply correct tax rates: If the customer is registered in the EU and has a valid VAT ID, they might be exempt from certain taxes or have specific VAT rules applied. If they are in a country with a different tax system (e.g., GST in Canada), the app must apply the correct GST rate.
Validate tax exemptions: The app can use the retrieved taxId to verify the customer's tax-exempt status with relevant authorities or internal records.
Generate compliant invoices: Invoices generated by the app must include the correct tax information, including the customer's tax ID where applicable, to meet legal requirements.

How the new API feature helps:

Your app can now easily query the customer's taxId using the Admin API as soon as they log in or during the checkout process.
This data can be stored within your app's database or directly used to inform tax calculations.
If a customer's tax ID is missing, your app can prompt them to enter it, perhaps via a dedicated field in their customer account or at checkout, ensuring that future transactions are handled correctly.
This automation significantly reduces manual errors, saves time for both the merchant and their customers, and ensures compliance with complex international tax laws.

Conclusion

The exposure of customer tax settings through the Shopify Admin GraphQL API is a powerful enhancement that developers can leverage to build more sophisticated and compliant applications. By enabling direct access to customer tax IDs, Shopify is simplifying a critical aspect of e-commerce operations. Developers who integrate this feature into their apps will be well-positioned to offer enhanced value to merchants, particularly those dealing with cross-border sales and complex tax regulations.