Admin GraphQL API / 2026-07

A customer's tax ID (VAT number)
can now be retrieved via the Admin API

Starting with API version 2026-07, the Customer object's taxSettings field becomes public. Tax IDs such as VAT numbers collected at checkout can now be read by apps via query.

On this page
  1. What's actually changing (understand it in 30 seconds)
  2. How it works: the query flow
  3. What you can and can't retrieve
  4. Access requirements (scopes and protected customer data)
  5. Relationship to B2B taxRegistrationId
  6. Sample query
  7. 5 points engineers should know
  8. 3 use cases you can apply to your work
  9. A one-line summary for pitches

1What's actually changing

API version 2026-07 onward, the Customer object's taxSettings field becomespublicin the Admin GraphQL API.
As a result, a customer'stax ID (such as a VAT number)collected and validated at checkout can now be read by apps via query.
private

Until now: not retrievable

Even when collected at checkout, a customer's tax ID could not be queried publicly from Customer in the Admin GraphQL API.

From 2026-07: readable

customer { taxSettings { taxId } } can retrieve the tax ID. This is a read-only change.

2How it works: the query flow

App read_customers or read_taxes query Admin GraphQL API version 2026-07 read-only Customer taxSettings taxId : "VAT..." / null Collected and validated at checkout Retrieve tax ID Invoicing / accounting / tax-exemption checks
The tax ID iscollected and validated at checkout. Rather than having the app collect it anew, the app reads a value Shopify already holds.

3What you can and can't retrieve

FieldDetailsHandling in the public API
taxSettings A tax settings container under the Customer object Public 2026-07~
taxSettings.taxId Tax ID (e.g., VAT number). A string, or, if not provided, null Retrievable read-only
taxSettings.taxIdValidation A subfield indicating the validation status of the tax ID Not in the public API
The validation status (taxIdValidation) is not part of the public API.To access this subfield,approved protected customer data accessis required.

4Access requirements

Reading taxId

read_customers or read_taxes — an app with this access scope can query taxId .

Using taxIdValidation

Apps that want to use the validation status must haveapproved protected customer data access(not yet included in the public API).

5Relationship to B2B's taxRegistrationId

This new Customer.taxSettings , for B2B, aligns with, already available CompanyLocation.taxSettings.taxRegistrationId(API version 2025-01 onward), and is addedin a consistentmanner.
Applies toFieldAvailable from
B2B Company location CompanyLocation.taxSettings.taxRegistrationId API 2025-01~
Regular customer Customer Customer.taxSettings.taxId API 2026-07 onward (this release)

Tax registration information that could previously only be retrieved on the company location side can now be handled on the regular Customer side with the same taxSettings structure.

6Sample query

{
  customer(id: "gid://shopify/Customer/customer_id") {
    taxSettings {
      taxId  // String, or null if not provided
    }
  }
}
taxId returns eithera string, or, if the customer hasn't provided one, null . The client must always account for the possibility of null in its handling.

75 points engineers should keep in mind

2026-07

1. From API version 2026-07 onward

This rollout requires API version 2026-07 or later. Unless you raise your app's target API version, taxSettings cannot be used.

2. Two scope options

read_customers or read_taxes , if you have either, taxId can be queried.

3. A read-only change

This is a read-only change. It is not meant for writing or updating tax IDs via the API. The values originate at checkout.

str / null

4. Be rigorous about null safety

taxId is either a string or nullIf the customer has not provided a tax ID, null is returned, so build with the assumption that it may be missing.

5. taxIdValidation requires a separate permission

The validation-status-indicating taxIdValidation subfield isnot included in the public API. To access it,approved protected customer data accessis required. Whether you can meet the requirement of knowing "is the number verified" depends on whether you have obtained this permission.

83 use cases you can apply to your operations

VAT number
USE CASE 1

Automatically pulling VAT numbers into invoicing and accounting integrations

Challenge
VAT numbers collected at checkout could not be retrieved from the Admin API, so they were transcribed by hand when issuing invoices or integrating with accounting / ERP systems.
Solution
In 2026-07, customer { taxSettings { taxId } } is queried and passed automatically to the invoicing and accounting systems.
Impact
Fewer transcription errors for tax IDs and less manual work. Recording the numbers on tax documents can be automated.
Technical notes
read_customers or read_taxes is required. Read-only.null(not provided): always include a branch to handle this case.
B2B B2C taxSettings
USE CASE 2

Helping tailor customer segments / tax-exemption flows

Challenge
The app could not tell whether a customer had a tax ID (i.e., was a business), so it could not build branching logic.
Solution
taxId value / null as a signal to branch flows and communications for the target customers.
Impact
Enables automatic routing of downstream processing, such as sending invoices or notices to customers who hold a tax ID.
Technical notes
Whether "the number is verified" requires taxIdValidation but it isn't available in the public API, sothis check separately requires Protected Customer Data Access. Determining only whether a number exists can be done with scopes alone.
Company Customer Unification
USE CASE 3

Extending B2B-ready apps to B2C customers

Challenge
Until now, CompanyLocation.taxSettings.taxRegistrationId(since 2025-01) only handled tax registration numbers for B2B company locations, so you couldn't retrieve a regular Customer's tax ID.
Approach
Incorporate the field added in 2026-07, Customer.taxSettings.taxId and process both B2B and regular customers with the same taxSettings structure.
Impact
Unifies the tax ID retrieval paths that were split between companies and individuals, simplifying code and operations.
Technical notes
Both taxSettings are designed to align via this, making field mapping easy to standardize. Watch out for the difference in target API versions (2025-01 / 2026-07).

9One-line summary you can use in a proposal

"As of API 2026-07, you can read and retrieve the tax ID (VAT number) of a customer collected at checkout via
Customer.taxSettings.taxId .
The required scope is read_customers or read_taxes,read-only.
only the verification status separately requires Protected Customer Data Access."