September 24, 2026 · Muhammad Rehan · More by Muhammad Rehan
What changeFromQuantity Actually Protects in Shopify
As of API 2026-04, four Shopify inventory mutations require changeFromQuantity. Here's what the check does and why opting out with null defeats it.
Starting in Shopify API version 2026-04, four inventory mutations require a changeFromQuantity argument. It's easy to treat this as a schema annoyance and pass null everywhere to make the error go away. That defeats the entire point of the field, and if you're writing inventory to Shopify from an ERP, WMS, or marketplace sync, it's worth understanding what you're opting out of before you do.
Where it applies
changeFromQuantity is now required at runtime on inventoryAdjustQuantities, inventoryMoveQuantities, inventorySetOnHandQuantities, and on the quantityAdjustments field of productVariantsBulkUpdate. It replaces the older compareQuantity and ignoreCompareQuantity fields that existed on inventorySetQuantities — Shopify's own release notes say to remove those entirely rather than keep them alongside the new field.
Notably, the requirement isn't enforced at the GraphQL schema level — you won't see it as non-nullable in introspection. It's a runtime check: omit it, and the mutation fails when it executes, not when you build the query.
What the check actually does
Pass the quantity you expect to currently be on hand, and Shopify turns your write into an optimistic concurrency check, sometimes called compare-and-swap. If the actual quantity in Shopify doesn't match what you passed, the mutation fails with a CHANGE_FROM_QUANTITY_STALE error instead of applying your change anyway.
That matters most for any integration that isn't the only writer of a given inventory item. If your ERP sync and, say, a POS adjustment or another app both touch the same SKU around the same time, the second write to arrive is the one at risk of silently overwriting the first's effect. changeFromQuantity turns that race into an explicit error you can catch and retry with the current value, rather than a quiet, wrong quantity sitting in Shopify.
Why passing null everywhere is the wrong default
You can still opt out by explicitly passing changeFromQuantity: null, and the mutation will behave the way inventory writes always used to — no concurrency check, whatever value you send is applied. Shopify's own guidance is direct about this: avoid opting out unless your use case actually justifies it. For most external inventory integrations, the use case doesn't justify it, since the entire reason to add ERP or WMS-driven inventory sync is to keep a single source of truth accurate, and skipping the check reintroduces exactly the overwrite risk the field exists to catch.
A related, separate change: mandatory idempotency
The same 2026-04 release also made idempotency mandatory for specific mutations covering inventory adjustments and refunds. This is a distinct protection: changeFromQuantity guards against two different processes overwriting each other's changes, while idempotency guards against your own retried request being applied twice. If you're building or auditing an integration against 2026-04, treat these as two separate checklist items rather than one — fixing one doesn't cover the other.