Executive summary
- What: Shopify is changing Events payloads, trigger syntax, and delivery headers. fields_changed becomes a structured object, parent triggers need an explicit wildcard, and two headers are removed.
- Why: Consumers can now tell additions, updates, and removals apart from the payload alone, without querying the Admin API to infer what actually happened.
- Who: Any team subscribed to Events on the unstable API version. Classic webhook subscriptions are unaffected, so most production integrations are not in scope today.
What changed
Four changes landed together. The first is the significant one. fields_changed was a flat array of changed paths, and it is now an object holding three arrays: added, updated, and removed. A variant added to a product keeps the product action as update and places the variant path under added, which is information the old shape simply did not carry. Previously you inferred intent by querying the resource and comparing state.
Second, subscribing to everything below a parent path now requires a terminal wildcard, so product.variants becomes product.variants.* in shopify.app.toml. Leaf triggers such as product.variants.price are unchanged. Existing subscriptions keep working, but you must update parent triggers the next time you deploy the TOML file, which makes this a deferred break rather than an immediate one. Matching behaviour and event volume are preserved for equivalent subscriptions.
Third, the shopify-event-id and shopify-resource-id delivery headers are removed as redundant. Updating your Shopify API packages handles this, but any custom code that reads those headers, particularly for validation or idempotency, needs that dependency removed. Fourth, event subscriptions using the update action now require at least one trigger.
Why it matters
Events is still in developer preview on the unstable API version, which sets the stakes correctly. This is not a production emergency for most Plus merchants, because classic webhooks carry the live integrations. It is a planning signal, since Shopify has stated Events will become the primary subscription mechanism as topic coverage expands.
The fields_changed restructure is worth understanding now rather than at migration time. Any integration that syncs orders, inventory, or product data to an ERP or an OMS spends real effort deciding whether a change was an addition or a removal, and the usual workaround is a reconciliation query per event. Getting that distinction in the payload removes a round trip per delivery and removes a class of race condition where the queried state has already moved on. For teams planning an Events migration alongside an ERP integration, we can help sequence the work.
Role-specific impact
- Marketers: no direct impact. Data flowing into downstream marketing systems is unchanged as long as the engineering team handles the payload shape.
- Developers: action is required. Update payload parsing for the three arrays, rewrite parent triggers with the terminal wildcard before your next TOML deploy, upgrade API packages, and drop any reliance on the two removed headers.
- Store admins: nothing to configure. Worth knowing that app partners may ship updates in response, so an unexpected app release note referencing webhook changes is likely related.
Use-case example
Real-world scenario
A merchant syncing a 40,000 SKU catalogue to Dynamics 365 subscribes to product changes and receives roughly 12,000 events on a heavy merchandising day. Under the flat fields_changed array, every event touching a variant path triggered an Admin API query to determine whether the variant was new, edited, or deleted, because the payload could not say. That is 12,000 extra queries against the API budget purely to classify intent. With added, updated, and removed separated in the payload, the classification query disappears for the majority of deliveries, and the sync stops misclassifying a deletion as an update when a query lands after a subsequent change.
Implementation checklist
- Confirm whether you use Events at all. If your subscriptions are classic webhooks, none of this applies.
- Update payload handling to read fields_changed.added, fields_changed.updated, and fields_changed.removed instead of a flat array.
- Rewrite parent triggers in shopify.app.toml with a terminal wildcard, and leave leaf triggers unchanged.
- Upgrade Shopify API packages to their latest versions so header handling is managed for you.
- Remove any custom code that reads shopify-event-id or shopify-resource-id, especially in validation or deduplication paths.
- Ensure every event subscription using the update action declares at least one trigger.
FAQ
Q: Do our existing webhook integrations break?
A: Classic webhook subscriptions are unaffected by all four changes. Only Events subscriptions on the unstable API version are in scope.
Q: How urgent is the trigger syntax change?
A: Existing subscriptions continue to work, so nothing breaks immediately. The constraint is that parent triggers must use the new syntax the next time you deploy shopify.app.toml, so handle it as part of your next planned deploy rather than as a hotfix.
Resources
Need guidance? Talk to Makro.