Why Shopify stock drifts from another system: locations, quantity states and set versus adjust

Stock in Shopify is per variant, per location, and in several states

A number in the Shopify admin hides structure. Stock is held for a product variant at each location, and at each location it is split into states. Shopify's developer documentation defines on hand as the sum of available, committed, reserved, damaged, safety stock and quality control. Available is what can be sold. Committed covers unfulfilled orders, reserved draft-order items and transfers or shipments marked ready to ship. Reserved, damaged, safety stock and quality control appear as unavailable in the admin.

This matters for any sync, because another system's single stock figure usually corresponds to only one of these states. If your warehouse system reports units on the shelf and Shopify reports available, the difference is exactly the committed and reserved units. Comparing the two without naming the state produces a gap that looks like drift but is arithmetic.

• Decide, in writing, which Shopify state matches the other system's sellable figure.
• Know which location the sync writes to, since each location has its own number.
• Some outside fulfilment services and dropshipping apps are themselves locations.

Set writes a final number; adjust writes a change

Shopify offers two ways to change stock through its Admin API. An adjust mutation applies a relative change, a delta, so going from 100 to 102 sends a delta of two. A set mutation writes an absolute value, and Shopify states that it should only be used by a system that is the authoritative source for stock counts. Otherwise the adjust mutation is advised.

The danger of an absolute write is timing. If the sync reads 100 from the other system, a customer buys two units in Shopify, and the sync then writes 100, the two sales are erased from Shopify's count and the item can be oversold. Shopify's set mutation guards against this with a comparison value: unless that check is skipped, the update goes through only if the stored quantity equals the value you supply. The documentation recommends always sending the comparison value and opting out only when necessary. In the current documentation version an idempotency key is also required, so a retried request can be recognised.

• A spreadsheet sync that pastes absolute numbers has no comparison, which is the usual cause of "sales disappeared".
• Version specifics change; check the version of the API your integration calls.

What Shopify does not tell your sync

Change notifications are not a complete feed. Shopify states that changes to committed, reserved, damaged, safety stock and quality control quantities do not fire webhooks, so an app that depends on those states must query for them. The general webhook guidance adds that delivery cannot be relied on every time, so a sync should not treat events as its only data source and should also run a periodic reconciliation that pulls current data.

The product CSV is not a fix either: its inventory quantity column applies to single-location stores only, so using a spreadsheet import to correct stock on a multi-location store is the wrong tool.

A safe first investigation

Pick three products that are wrong and write down, for each, the Shopify available quantity at the location the sync is meant to update, the committed quantity, and the other system's sellable figure. Then run the arithmetic before suspecting a fault.

• Does available plus committed equal the other system's on-hand figure?
• Is the gap constant, or does it grow with each sync run?
• Does the gap match the number of open orders for that product?
• Is the sync writing to the same location that sells the product?
• Does the sync write absolute numbers or changes?

What fixes it, and what does not fit

Fixes change the rule, not the numbers: agree which system is authoritative, map each location, compare before writing or send changes instead of totals, and add a periodic reconciliation pass. A physical count, product-code clean-up across both systems, and a paid connector's internal bugs are outside a settings-and-logic fix; for a connector, send the reconciliation to the vendor.

How the paid fix is accepted

The fixed job for this problem is accepted on a test store with a copy of your sync and a copy or sandbox of the other system, so nothing is written to your live systems. For the agreed products at the agreed location, Shopify available stock equals the other system's sellable figure under the written rule; a repeat run changes nothing; a test sale reduces both systems once; and when the copy is held between its read and its write, a sale placed in between is not overwritten. You apply the corrected logic to your live sync; we never receive store keys.