Shopify’s latest developer update simplifies the way third‑party tax apps interact with the platform. As of API version 2027-01, every entity reference in tax calculation requests and tax summary webhook payloads is expressed as a Global ID (GID). This shift aligns tax integrations with the rest of Shopify’s API ecosystem, eliminating the need to juggle multiple ID formats. In this post we’ll break down exactly what changed, who needs to act, and how to bring your code up to speed.
What Changed: Global IDs Everywhere
Previously, tax‑related payloads mixed raw integer IDs (e.g., "customer": {"id": "5"}) with Shopify’s newer GID format used elsewhere. The new schema standardizes every reference to the GID pattern "gid://shopify/<Entity>/<ID>". The change touches two integration points:
shop_admin_graphql_api_id, order_admin_graphql_id, and admin_graphql_api_id for the TaxSummary itself.The payload examples in the changelog illustrate the shift: a customer ID goes from "5" to "gid://shopify/Customer/5", a line item ID becomes "gid://shopify/LineItem/12", and the webhook now carries admin GraphQL IDs for the shop and order.
Who Is Affected: Developers vs. Merchants
Developers building or maintaining third‑party tax apps are the primary audience. Their code that parses tax calculation requests or consumes the tax summary webhook must accept the GID format, otherwise lookups will fail or produce unexpected results.
Merchants generally won’t see a visual change in their admin, but they may notice errors if an installed tax app hasn’t been updated. A mis‑parsed ID can lead to incorrect tax calculations, delayed order fulfillment, or even webhook delivery retries.
How to Update Your Tax Calculation Requests
The change is straightforward: wherever your app builds or reads the request payload, replace raw integer IDs with the GID string. Below is a before‑and‑after snippet for the buyer identity block.
// Before (API <= 2026-10)
{"cart":{"buyer_identity":{"customer":{"id":"593934299"}}}}
// After (API >= 2027-01)
{"cart":{"buyer_identity":{"customer":{"id":"gid://shopify/Customer/593934299"}}}}
If you generate IDs programmatically, use Shopify’s helper function (available in most SDKs) to convert an integer to a GID: ShopifyID.encode('Customer', id) or, in Ruby, ShopifyAPI::GID.encode('Customer', id). This ensures consistency across all endpoints.
Handling the Updated Tax Summary Webhook
The webhook payload now includes GIDs for every nested entity and adds three admin GraphQL IDs at the top level. A typical updated payload looks like this:
{
"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"
}]
}]
}
}
To adapt:
id fields as opaque strings. If you need the numeric part, split on the last slash (/) or use Shopify’s SDK to decode.Testing and Validation
2027-01 (or later) in the Shopify Partner Dashboard. The platform will automatically start sending GIDs.gid://shopify/... pattern.Conclusion & Next Steps
The move to Global IDs for tax calculations and summary webhooks is a small but powerful step toward a unified Shopify API surface. By updating your app to recognize GIDs, you reduce friction, eliminate duplicate ID‑translation logic, and future‑proof your integration against upcoming API changes.
Ready to upgrade? Switch your app’s API version to 2027-01, refactor the ID handling as shown above, and deploy to a staging store. If you hit any roadblocks, the Shopify dev forums and the official API reference are excellent resources. Happy coding!
