Introduction to Global IDs in Tax Webhook Changes
Starting with Shopify API version 2026-01, third-party tax applications now leverage Global IDs (GIDs) for entity references in tax calculation requests and tax summary webhook payloads. This update streamlines integrations and aligns with Shopify's standard API practices.
What Has Changed?
Impact on Tax Calculation Requests
Entities in tax calculation requests, such as customers, companies, product variants, and locations, will now utilize the GID format. For example:
- Customer IDs change from "id": "5" to "id": "gid://shopify/Customer/5".
- Product IDs change from "id": "1" to "id": "gid://shopify/Product/1".
- Company Location IDs change from "id": "4" to "id": "gid://shopify/CompanyLocation/4".
Impact on Tax Summary Webhooks
Tax summary webhooks now include GIDs for all entity IDs in the summary section. Additionally, new fields — shop_admin_graphql_api_id, order_admin_graphql_api_id, and tax_summary_admin_graphql_api_id — have been added while retaining existing integer-based IDs.
Examples of the GID Format Transition
Before (API Version 2025-10 and Earlier)
{ "cart": { "buyer_identity": { "customer": { "id": "593934299" } } } }After (API Version 2026-01)
{ "cart": { "buyer_identity": { "customer": { "id": "gid://shopify/Customer/593934299" } } } }What You Need to Do
If your Shopify integration processes tax calculations or webhook payloads, ensure it is updated to handle GIDs effectively for API version 2026-01 and beyond. Examples of entities requiring GID updates include:
- TaxSummary (Use GID
gid://shopify/TaxSummary/80). - Order (Use GID
gid://shopify/Order/64). - Line Items (Use GID
gid://shopify/LineItem/76). - SalesAgreements and Sales (e.g.,
gid://shopify/SalesAgreement/82).
Conclusion
This update enhances consistency and simplifies integration management across Shopify APIs. By utilizing GIDs, you can ensure smoother handling of tax-related data across endpoints. Update your applications promptly to accommodate these changes.