税務Webhook/計算リクエストがGIDに統一

11月 04, 2026

TAX API

税務Webhook・計算リクエストがGIDに統一

APIバージョン2027-01以降、税務系の全エンティティIDが gid://shopify/… 形式へ移行

サードパーティ税務アプリを構築・運用しているパートナーが対象です。2027-01バージョン以降、税計算リクエストと税務サマリWebhookペイロード内のすべてのエンティティIDが gid://shopify/[Type]/[id] 形式（GID）に変わります。既存の整数・整数文字列IDの処理ロジックは改修が必要です。

1Before / After で見る変更点

2業務に活かせる具体ユースケース

課題: 独自の税務計算エンジンで顧客IDを受け取り、Shopify Admin GraphQL APIで顧客情報を追加取得していたが、REST形式の整数IDとGIDを相互変換する変換レイヤーを維持するコストが高かった。
打ち手: 2027-01移行後は計算リクエストの customer.id がそのままGIDで渡されるため、変換レイヤーを廃止しGraphQL API直接参照に切り替える。
効果: コード量削減・変換バグのリスクゼロ化。Admin GraphQL APIとID空間が統一されるため、顧客の購買履歴や企業情報との突合が簡単になる。
技術メモ: GIDから数値部分だけ取り出す場合は gid.split('/').pop() などで抽出可能。ただし変換後のIDをDBに保存する場合はGIDのままで保持する設計を推奨。

課題: 税務サマリWebhookを受信して外部会計システムに転記する際、OrderやShopのIDがWebhookに含まれておらずGraphQL APIで都度引き直す処理が必要だった。
打ち手: 2027-01以降は order_admin_graphql_api_id と shop_admin_graphql_api_id がトップレベルに追加されるため、Webhookペイロードだけで転記に必要なIDが揃う。
効果: 追加のAPI呼び出しが不要になり処理レイテンシを削減。Webhookハンドラのシンプル化と障害ポイントの削減が期待できる。
技術メモ: 従来の shop_id・order_id（整数）は2027-01以降も引き続き送信される。段階的移行として新旧フィールドを並列で検証し、切り替えタイミングを調整できる。

課題: B2B向け税務アプリでCompany・CompanyLocationのIDを管理していたが、税務API用のID形式とGraphQL API用GIDが異なり、マッピングテーブルを別途管理する必要があった。
打ち手: GID統一後は計算リクエストおよびWebhookの両方で gid://shopify/Company/…・gid://shopify/CompanyLocation/… が返ってくるため、マッピングテーブルを廃止できる。
効果: B2B税務ロジックの実装コストを大幅削減。CompanyLocationごとの免税設定や適用税率の判定処理をGraphQL APIと直接紐付けられる。
技術メモ: Company・CompanyLocationはB2B（法人EC）機能に依存するため、利用している場合は計算リクエスト・Webhook双方の改修が必要。

3技術者向けポイント

観点	詳細
適用バージョン	API version 2027-01 以降。2026-10以前は従来の整数・整数文字列IDが継続。
後方互換性	`shop_id`・`order_id` の整数フィールドは2027-01以降も引き続き送信される。GIDフィールドは追加扱い。
対象エンティティ全リスト	計算リクエスト: Customer / Company / CompanyLocation / Product / ProductVariant。Webhook summaryセクション: Order / Customer / Product / ProductVariant / SalesAgreement / Sale / LineItem / Company / CompanyLocation / ShippingLine / TaxLine。Webhookトップレベル追加: TaxSummary / Shop / Order の `admin_graphql_api_id`。
TaxLine IDの型変化	TaxLine のみ整数 → 文字列GID に型が変わる点に注意。JSONパーサーの型チェックが厳密な実装は特に要確認。
移行手順の推奨	①テスト環境で2027-01バージョンのリクエスト・Webhookを受信し動作確認 → ②GIDパーサー/バリデーションロジックを追加 → ③本番バージョンアップ。元記事に旧IDの廃止時期の記載はなし。

⚠️ 型変更に要注意: TaxLine
他のエンティティが「文字列 → GID文字列」であるのに対し、TaxLineだけは "id": 6（数値型）から "id": "gid://shopify/TaxLine/6"（文字列型）への変更です。型を厳格に扱う言語・ライブラリでは特別な対応が必要になります。

※ 元記事のサンプルコード内に「202-01」と記載されているバージョン表記は誤植と思われます。公式ドキュメントで「2027-01」であることを必ずご確認ください。

税務サードパーティアプリのID処理を2027-01バージョンに対応させることで、全ShopifyエンドポイントでGIDが統一され、変換レイヤー廃止・API連携コストの大幅削減が実現できます。

Source: https://shopify.dev/changelog/tax-webhook-summary-and-calculation-requests-now-use-global-ids | 公開日: 2026年10月1日