税務Webhookサマリーと計算リクエストがグローバルIDを使用するようになりました

1. 技術的課題の定義

今までShopifyの税務計算リクエストや税務サマリーWebhookのペイロードでは、サマリーセクションのエンティティ参照には各々異なる形式のIDが用いられてきました。これは、異なるID形式を管理しなければならないため、開発者にとっては複雑さを増す要因となっていました。

2. 現状の技術スタックと問題分析

APIバージョン2026-01から、サードパーティの税務アプリは、税務計算リクエストと税務サマリーWebhookのペイロードにおいて、全エンティティ参照のサマリーセクションでグローバルID（GID）を受け取ります。これは他のShopify APIとのやり取りと一致します。

これにより、アプリはすべてのShopifyエンドポイントで同じ識別子を使用し、税務特定の統合のために異なるID形式を管理する必要がなくなります。

3. 技術的ソリューションの提案

APIバージョン2026-01以降、GID形式を使用することで、税務計算の処理やWebhookペイロードをよりシンプルに、かつ一貫性を持って扱うことが可能になります。具体的には次のような変更が含まれます：

• 税務計算リクエスト：Customer、Company、CompanyLocation、Product、ProductVariantのIDがGID形式を使用します。
• 税務サマリーWebhook：サマリーセクション内のすべてのエンティティID（Order、Customer、Product、ProductVariant、SalesAgreement、Sale、LineItem、Company、CompanyLocation、ShippingLine、TaxLine）がGID形式を使用します。
• Webhookペイロードには新たに、TaxSummary、Shop、Orderエンティティのトップレベルでadmin_graphql_api_idフィールドが含まれます。

4. 実装手順とコード例

サードパーティの税務アプリは、APIバージョン2026-01以降を使用して税務計算とWebhookペイロードを処理する際に、GID形式を扱うことが要求されます。以下にその具体例を示します：

税務計算リクエスト

変更前（2025-10以前）：

{
  "cart": {
    "buyer_identity": {
      "customer": {
        "id": "593934299"
      }
    }
  }
}

変更後（2026-01以降）：

{
  "cart": {
    "buyer_identity": {
      "customer": {
        "id": "gid://shopify/Customer/593934299"
      }
    }
  }
}

税務サマリーWebhook

変更前（2025-10以前）：

{
  "id": 80,
  "shop_id": 1,
  "order_id": 64,
  "summary": {
    "agreements": [{
      "id": "82",
      "sales": [{
        "id": "106",
        "line_item_id": "76"
      }]
    }]
  }
}

変更後（2026-01以降）：

{
  "id": 80,
  "admin_graphql_api_id": "gid://shopify/TaxSummary/80",
  "shop_id": 1,
  "shop_admin_graphql_api_id": "gid://shopify/Shop/1",
  "order_id": 64,
  "order_admin_graphql_api_id": "gid://shopify/Order/64",
  "summary": {
    "agreements": [{
      "id": "gid://shopify/SalesAgreement/82",
      "sales": [{
        "id": "gid://shopify/Sale/106",
        "line_item_id": "gid://shopify/LineItem/76"
      }]
    }]
  }
}

5. パフォーマンス・コスト分析

この変更では、各エンティティのIDを一貫したGID形式にすることで、IDの管理が簡素化されます。これにより、誤ったID形式によるエラーや、異なるID形式の変換によるパフォーマンスの低下を防ぐことができます。また、開発者の作業負荷も軽減されるため、開発コストの削減にも寄与します。

6. 実装時の注意点・ベストプラクティス

GID形式を適切に取り扱うためには、APIバージョン2026-01以降を使用していることを確認してください。また、各エンティティのIDがGID形式に変更されるため、これまでのID形式を使用したコードがある場合は適切に更新する必要があります。

7. 次のステップ・発展案

今後のAPIバージョンでは、さらに多くのエンティティがGID形式のIDを使用するようになる可能性があります。開発者はShopify APIの最新の変更を常にチェックし、新しい形式に適応する準備をしておくことが重要です。

参考記事: Tax webhook summary and calculation requests now use Global IDs