Shopify Events: payload structure is changing

Shopify Events structure change: what's happening

Shopify Events is not a classic webhook. It's a more granular system, designed to notify specific changes to store resources, and as of now its structure is changing substantially. If your app or integration reads Events payloads, updating your code is not optional: without action, the risk of breakage is real.

This change particularly affects anyone who has built custom logic on middleware, ERP systems, or data synchronization pipelines based on the Events API.

The concrete changes to the payload

The updates introduced by Shopify affect both the data structure and subscription configuration.

fields_changed becomes a structured object

Until now, fields_changed was a flat array listing modified fields without distinguishing the type of change. Now it becomes an object with three distinct arrays:

• added, for added fields
• updated, for modified fields
• removed, for removed fields

A practical example: adding a variant to a product now shows up in fields_changed.added, no longer in a generic undifferentiated array. This means the payload itself communicates the type of operation that occurred, without ambiguity.

Parent triggers with explicit wildcard

Triggers that reference a parent resource now require an explicit wildcard. A trigger like product.variants must be rewritten as product.variants.*. This change needs to be reflected in the app's configuration file, shopify.app.toml, before the next deploy.

Delivery headers removed

Two headers previously used to identify events and resources are no longer present in delivery requests:

• shopify-event-id
• shopify-resource-id

Any logic that depends on these headers for parsing or deduplicating events needs to be revised.

Subscriptions with update action

Subscriptions using the update action must now have at least one trigger defined. Configurations without explicit triggers will no longer be valid.

Why this change matters

The core of this update is a paradigm shift in how integrations interpret events. Previously, understanding what had actually changed on a resource often required querying the API again and comparing the previous state with the current one. Now the payload directly communicates the nature of the change, reducing redundant API calls and simplifying processing logic on the middleware or ERP side.

This is therefore a structural improvement, but one that requires active intervention from anyone managing integrations based on the Events API.

What to do right away

For those developing or maintaining Shopify apps and integrations, here are the steps to address before the next deploy:

• Update the logic that reads fields_changed to use .added, .updated and .removed instead of the previous flat array
• Remove any dependency on the shopify-event-id and shopify-resource-id headers
• Update shopify.app.toml with the wildcard syntax on parent triggers
• Update Shopify API packages to the latest available version

Classic Webhooks are not affected

It's important to clarify that Classic Webhook subscriptions are not affected by this change: they continue to work as before. The issue applies exclusively to those using the Events API, especially with custom logic on middleware or integration systems with external ERPs.

If your company manages complex Shopify integrations, it's worth planning a code audit of anything consuming Events before the next deploy, to avoid unexpected disruptions to critical data synchronization flows.

A change worth monitoring over time

Updates like this confirm how important it is to keep integrations aligned with the evolution of the Shopify platform, especially when working with advanced automation logic. For those managing custom Shopify development projects, relying on specialized technical expertise makes it possible to anticipate these changes rather than be caught off guard by them. Anyone wanting to learn more about costs and ways of working with a Shopify development team can check the Shopify developer pricing page to evaluate an audit or a targeted update.

Monitoring Shopify's official changelogs remains the most effective practice to avoid being caught off guard by structural changes like this one.