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

図解 ： Customer tax settings が Admin API で取得可能に（顧客の税 ID / VAT 番号） Admin GraphQL API / 2026-07 顧客の税 ID（VAT 番号）が Admin API で取得できるようになる API バージョン 2026-07 以降、Customer オブジェクトの taxSettings フィールドが公開化。チェックアウトで集めた VAT 番号などの税 ID を、アプリから読み取りクエリできるようになる。 このページの構成 そもそも何が変わるのか（30秒で理解） 仕組み図解 ： クエリの流れ 取れるもの／取れないもの アクセス要件（スコープと保護対象顧客データ） B2B の taxRegistrationId との関係 サンプルクエリ 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何が変わるのか API バージョン 2026-07 から、Customer オブジェクトの taxSettings フィールドが Admin GraphQL API で 公開 される。 これにより、チェックアウト時に収集・検証された顧客の 税 ID（VAT 番号など） を、アプリからクエリで読み取れるようになる。 これまで ： 取得不可 顧客の税 ID はチェックアウトで集めても、Admin GraphQL API の Customer から公開クエリできなかった。 2026-07〜 ： 読み取り可 customer { taxSettings { taxId } } で税 ID を取得できる。読み取り専用の変更。 2 仕組み図解 ： クエリの流れ 税 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 には未収録）。 5 B2B の 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つのポイント 1. API バージョン 2026-07 から この公開は API バージョン 2026-07 以降が前提。アプリのターゲット API バージョンを上げないと taxSettings は利用できない。 2. 必要スコープは2択 read_customers または read_taxes のいずれかがあれば taxId をクエリできる。 3. 読み取り専用の変更 これは read-only な変更。API 経由で税 ID を書き込み・更新する用途ではない。値の発生源はチェックアウト。 4. null セーフを徹底 taxId は文字列か null 。顧客が税 ID を提供していなければ null が返るため、欠損前提で実装する。 5. taxIdValidation は別枠の権限が必要 検証ステータスを示す taxIdValidation サブフィールドは 公開 API に含まれない 。アクセスするには 承認済みの保護対象顧客データ（protected customer data）アクセス が必須。「番号が検証済みか」を知りたい要件は、この権限取得の有無で実現可否が分かれる。 8 業務に活かせる3つのユースケース USE CASE 1 請求書・会計連携への VAT 番号の自動取り込み 課題 チェックアウトで集めた VAT 番号が Admin API から取れず、請求書発行や会計 / ERP 連携の際に手作業で転記していた。 打ち手 2026-07 で customer { taxSettings { taxId } } をクエリし、請求・会計システムへ自動で渡す。 効果 税 ID の転記ミス削減と工数削減。税務書類への番号記載を自動化できる。 技術メモ read_customers か read_taxes が必要。read-only。 null （未提供）時の分岐を必ず用意。 USE CASE 2 顧客セグメント／免税フローの出し分け補助 課題 税 ID を持つ顧客（事業者）かどうかをアプリ側で把握できず、出し分けロジックが組めなかった。 打ち手 taxId の値 / null をシグナルにして、対象顧客のフローやコミュニケーションを分岐させる。 効果 税 ID 保有顧客への請求書送付や案内など、後続処理の自動振り分けが可能に。 技術メモ 「番号が検証済みか」は taxIdValidation が必要だが公開 API に無いため、 この判定には保護対象顧客データアクセスが別途必要 。番号の有無だけならスコープのみで判定可。 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。 検証ステータスだけは保護対象顧客データアクセスが別途必要。」 source ： shopify.dev / changelog / customer-tax-settings-now-available-in-admin-api 公開日 2026-04-24（Developer Changelog）