Tax webhook summary and calculation requests now use Global IDs

Starting with API version 2026-01, third-party tax apps will receive Global IDs (GIDs) in tax calculation requests and tax summary webhook payloads for all entity references of the summary section. This aligns with how Partners interact with other Shopify APIs.

These apps can now use the same identifiers across all Shopify endpoints without managing different ID formats for tax-specific integrations.

What's changed

This change affects two key integration points:

Tax calculation requests:

• Customer, Company, CompanyLocation, Product, and ProductVariant IDs now use the GID format.

Tax summary webhooks:

• All entity IDs within the summary section (Order, Customer, Product, ProductVariant, SalesAgreement, Sale, LineItem, Company, CompanyLocation ShippingLine, and TaxLine) now use the GID format.
• The webhook payload also includes new admin_graphql_api_id fields at the top level for TaxSummary, Shop, and Order entities.

Changes include:

• Top Level: Adds shop_admin_graphql_api_id and order_admin_graphql_api_id fields (existing shop_id and order_id remain as integers).
• Customer IDs: Changes from "id": "5" to "id": "gid://shopify/Customer/5".
• Product IDs: Changes from "id": "1" to "id": "gid://shopify/Product/1".
• Product Variant IDs: Changes from "id": "1" to "id": "gid://shopify/ProductVariant/1".
• Line Item IDs: Changes from "line_item_id": "5" to "line_item_id": "gid://shopify/LineItem/5".
• Sale IDs: Changes from "id": "9" to "id": "gid://shopify/Sale/9".
• Agreement IDs: Changes from "id": "6" to "id": "gid://shopify/Agreement/6".
• Company IDs: Changes from "id": "3" to "id": "gid://shopify/Company/3".
• Company Location IDs: Changes from "id": "4" to "id": "gid://shopify/CompanyLocation/4".
• Shipping Line IDs: Changes from "id": "4" to "id": "gid://shopify/ShippingLine/4".
• Tax Line IDs: Changes from "id": 6 to "id": "gid://shopify/TaxLine/6".

What you need to do

Update your integrations to handle the GID format when processing tax calculations and webhook payloads in API version 2026-01 and later. The following are some examples:

Tax calculation request

Before (2025-10 and earlier):

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

After (2026-01):

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

Tax summary webhook

Before (2025-10 and earlier):

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

After (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"
      }]
    }]
  }
}