Admin GraphQL API / 2026-07

顧客の税 ID（VAT 番号）が
Admin API で取得できるようになる

API バージョン 2026-07 以降、Customer オブジェクトの taxSettings フィールドが公開化。チェックアウトで集めた VAT 番号などの税 ID を、アプリから読み取りクエリできるようになる。

このページの構成
  1. そもそも何が変わるのか（30秒で理解）
  2. 仕組み図解 ： クエリの流れ
  3. 取れるもの／取れないもの
  4. アクセス要件（スコープと保護対象顧客データ）
  5. B2B の taxRegistrationId との関係
  6. サンプルクエリ
  7. 技術者が押さえるべき5つのポイント
  8. 業務に活かせる3つのユースケース
  9. 提案で使える1行サマリ

1そもそも何が変わるのか

API バージョン 2026-07 から、Customer オブジェクトの taxSettings フィールドが Admin GraphQL API で公開される。
これにより、チェックアウト時に収集・検証された顧客の税 ID（VAT 番号など）を、アプリからクエリで読み取れるようになる。
private

これまで ： 取得不可

顧客の税 ID はチェックアウトで集めても、Admin GraphQL API の Customer から公開クエリできなかった。

2026-07〜 ： 読み取り可

customer { taxSettings { taxId } } で税 ID を取得できる。読み取り専用の変更。

2仕組み図解 ： クエリの流れ

アプリ read_customers or read_taxes query Admin GraphQL API version 2026-07 read-only Customer taxSettings taxId : "VAT…" / null checkout で収集・検証済み 税 ID を取得 請求書 / 会計 / 免税判定
税 ID はチェックアウト時に収集・検証されたもの。アプリ側で新たに入力させるのではなく、Shopify が既に保持している値を読み取る形になる。

3取れるもの／取れないもの

フィールド内容公開 API での扱い
taxSettings Customer オブジェクト配下の税設定コンテナ 公開 2026-07〜
taxSettings.taxId 税 ID（VAT 番号など）。文字列、または未提供なら null 取得可 read-only
taxSettings.taxIdValidation 税 ID の検証ステータスを示すサブフィールド 公開 API に含まれない
検証ステータス（taxIdValidation）は公開 API には入っていない。このサブフィールドへアクセスするには、承認済みの保護対象顧客データ（protected customer data）アクセスが必要。

4アクセス要件

taxId の読み取り

read_customers または read_taxes のアクセススコープを持つアプリで taxId をクエリできる。

taxIdValidation の利用

検証ステータスを使いたいアプリは、承認済みの保護対象顧客データアクセスを持つ必要がある（公開 API には未収録）。

5B2B の taxRegistrationId との関係

今回の Customer.taxSettings は、B2B 向けにすでに提供されている CompanyLocation.taxSettings.taxRegistrationId（API バージョン 2025-01〜）と整合する形で追加される。
対象フィールド提供開始
B2B 法人ロケーション CompanyLocation.taxSettings.taxRegistrationId API 2025-01〜
通常顧客 Customer Customer.taxSettings.taxId API 2026-07〜（今回）

これまで法人ロケーション側でしか取れなかった税登録情報が、通常の Customer 側でも同じ taxSettings 構造で扱えるようになる。

6サンプルクエリ

{
  customer(id: "gid://shopify/Customer/customer_id") {
    taxSettings {
      taxId  // 文字列、未提供なら null
    }
  }
}
taxId は文字列、または顧客が未提供なら null を返す。クライアント側は必ず null を想定したハンドリングを行うこと。

7技術者が押さえるべき5つのポイント

2026-07

1. API バージョン 2026-07 から

この公開は API バージョン 2026-07 以降が前提。アプリのターゲット API バージョンを上げないと taxSettings は利用できない。

2. 必要スコープは2択

read_customers または read_taxes のいずれかがあれば taxId をクエリできる。

3. 読み取り専用の変更

これは read-only な変更。API 経由で税 ID を書き込み・更新する用途ではない。値の発生源はチェックアウト。

str / null

4. null セーフを徹底

taxId は文字列か null。顧客が税 ID を提供していなければ null が返るため、欠損前提で実装する。

5. taxIdValidation は別枠の権限が必要

検証ステータスを示す taxIdValidation サブフィールドは公開 API に含まれない。アクセスするには承認済みの保護対象顧客データ（protected customer data）アクセスが必須。「番号が検証済みか」を知りたい要件は、この権限取得の有無で実現可否が分かれる。

8業務に活かせる3つのユースケース

VAT番号
USE CASE 1

請求書・会計連携への VAT 番号の自動取り込み

課題
チェックアウトで集めた VAT 番号が Admin API から取れず、請求書発行や会計 / ERP 連携の際に手作業で転記していた。
打ち手
2026-07 で customer { taxSettings { taxId } } をクエリし、請求・会計システムへ自動で渡す。
効果
税 ID の転記ミス削減と工数削減。税務書類への番号記載を自動化できる。
技術メモ
read_customers か read_taxes が必要。read-only。null（未提供）時の分岐を必ず用意。
B2B B2C taxSettings
USE CASE 2

顧客セグメント／免税フローの出し分け補助

課題
税 ID を持つ顧客（事業者）かどうかをアプリ側で把握できず、出し分けロジックが組めなかった。
打ち手
taxId の値 / null をシグナルにして、対象顧客のフローやコミュニケーションを分岐させる。
効果
税 ID 保有顧客への請求書送付や案内など、後続処理の自動振り分けが可能に。
技術メモ
「番号が検証済みか」は taxIdValidation が必要だが公開 API に無いため、この判定には保護対象顧客データアクセスが別途必要。番号の有無だけならスコープのみで判定可。
Company Customer 統一
USE CASE 3

B2B 対応アプリを B2C 顧客まで拡張

課題
これまで CompanyLocation.taxSettings.taxRegistrationId（2025-01〜）で B2B 法人ロケーションの税登録番号だけ扱っていて、通常 Customer の税 ID が取れなかった。
打ち手
2026-07 で追加された Customer.taxSettings.taxId を取り込み、B2B / 通常顧客の両方を同じ taxSettings 構造で処理する。
効果
法人・個人で分かれていた税 ID 取得経路を1本化し、コードと運用をシンプルにできる。
技術メモ
両者ともに taxSettings で整合する設計なので、フィールドマッピングを揃えやすい。対象 API バージョンの差（2025-01 / 2026-07）に注意。

9提案で使える1行サマリ

「API 2026-07 から、チェックアウトで集めた顧客の税 ID（VAT 番号）を
Customer.taxSettings.taxId で読み取り取得できる。
必要スコープは read_customers か read_taxes、read-only。
検証ステータスだけは保護対象顧客データアクセスが別途必要。」