Inventory truth: the number three systems disagree about

The three numbers on the screen are usually all correct. They are answering different questions.

The warehouse knows what is on the shelf, as of the last time somebody scanned something. The ERP knows what it believes it owns, which includes goods in transit, allocations against purchase orders, and stock it has committed to a wholesale customer nobody told the website about. Shopify knows what it can sell, which is what it has been told exists minus what customers have already bought and it has not yet shipped.

The instinct is to make all three show the same figure. That instinct is wrong, and chasing it is how integration projects consume six months. Three systems with different jobs will legitimately show different numbers; what you need is not agreement but a defined relationship — which number derives from which, in which direction, and who is allowed to write.

Shopify's own model shows how much structure is already available. The documentation lists eight quantity states: incoming, on hand, available, committed, reserved, damaged, safety stock and quality control. And it defines the relationship arithmetically — on hand "equals the sum of inventory quantities in the following states: available, committed, reserved, damaged, safety stock, quality control". Most disagreements dissolve once the two sides work out they were comparing on hand against available.

Ownership is not one decision. It is three, and separating them is most of the design work.

On hand belongs to whoever counts. The physical count is an observation of the real world, and only the system in the room can make it. For a merchant using a 3PL, that is the 3PL. For a merchant with its own warehouse and a WMS, that is the WMS. The ERP is usually the wrong answer here, and it is the one most often proposed — because the ERP is the system finance trusts, and trust is not the same as knowledge. An ERP that receives its own counts from the warehouse is a relay, and a relay should not be the source.

Committed belongs to Shopify, and you have no choice. The documentation is direct: apps cannot directly modify committed quantities, because Shopify manages them through orders, draft orders and fulfilments. This is a feature. The commitment is created at the moment of sale, in the system where the sale happened, without a round trip. Any design that tries to calculate commitments elsewhere and push them in is fighting the platform and will lose during a busy hour.

Available is arithmetic, not an opinion. Once on hand is owned and committed is owned, available follows. The failure mode is two systems both writing available on their own schedules, each computing it from a partial view, overwriting each other in whatever order the queue happened to run.

The reason this matters commercially is specific: available is what gates the sale. Get its inputs wrong and you either oversell — cancellations, refunds, a support queue — or you undersell, which is worse because it is invisible. Nobody files a ticket about the thing they could not buy.

The single biggest reliability decision in an inventory integration is whether you send "there are 14" or "subtract 2".

Deltas are seductive because they are small and they seem to compose. They do not survive the real world. A delta applied twice is wrong, a delta lost is wrong, and both are permanent — there is no subsequent message that corrects them, so the error persists until somebody counts the shelf. Retries, at-least-once delivery and out-of-order processing are normal conditions in any queue, which means duplicate and dropped messages are not edge cases.

Absolute values are self-healing. Send "there are 14" and it does not matter whether the previous message arrived, arrived twice, or arrived late — the next message brings the system back to correct. Shopify supports this directly: inventorySetQuantities sets the available or on-hand quantity using absolute values, and the documentation frames it as the mutation for a system acting as the authoritative source.

It also gives you a defence against the one race condition that matters. The mutation accepts compareQuantity, which only applies the update if the persisted quantity matches what you believed it was, and fails with an error otherwise. That turns a silent overwrite into a visible conflict you can re-read and retry. There is an ignoreCompareQuantity escape hatch, and Shopify discourages it because bypassing the check risks accuracy problems under concurrent load. Use the escape hatch for a genuine reset after a stocktake, not because a conflict error appeared in your logs and you wanted it to stop.

inventoryAdjustQuantities still has a place — Shopify describes it for incrementing or decrementing across the adjustable states, which is what a correction or a damage write-off actually is. The rule of thumb: the sync sets, the exception adjusts.

Almost every merchant wants a cushion — publish slightly less than you have, so a counting error does not become an oversell. Almost every integration implements this by quietly subtracting a number before writing to Shopify.

That is where it goes wrong. The subtraction is invisible to everyone outside the integration, so the warehouse sees 20, Shopify shows 18, and now the two systems disagree by a rule that lives in code nobody reads. Six months later someone changes it from 2 to 3 and the discrepancy report nobody trusted gets slightly worse.

Shopify has a state for this. Safety stock is one of the eight documented quantity states, and it is one of the states an app can adjust. Put the buffer there, and the arithmetic stays honest: on hand is still the physical count, safety stock holds the cushion explicitly, and available comes out lower for a reason anyone can see in the admin. Damaged and quality control work the same way for stock that physically exists but must not be sold — a returns pile awaiting inspection is not a counting error, it is quality control, and modelling it as one makes the difference explicable.

The general principle: every unit of the gap between what is on the shelf and what you will sell should be attributable to a named state. A discrepancy you can explain is an operational decision. A discrepancy you cannot is a bug you will spend a week looking for.

Three proposals come up in nearly every inventory project, and each is more expensive than the problem it solves.

"Make the ERP the source of truth for stock." Usually wrong, for the reason above: the ERP is a relay for physical counts, not an observer of them. Finance can own valuation, cost and ownership while the warehouse owns the count. Those are different questions and one system does not have to answer both.

"Buy an inventory platform to sit in the middle." Sometimes justified — genuinely multi-channel merchants with several fulfilment points do reach this — but it is frequently bought to avoid making the ownership decision, and it cannot avoid it. A middle layer with no agreed owner produces a four-way disagreement instead of a three-way one, and adds a subscription.

"Sync every minute." Frequency is not the fix for a correctness problem. If the writes are deltas, faster syncing propagates errors faster; if they are absolute with compare-and-set, an hourly cadence with event-driven updates on the SKUs that move is usually enough. The stores that oversell are almost never the ones that synced too slowly. They are the ones where two systems both thought they owned the same number.

• Shopify integrations and back-end work
• Connecting a WMS when you already have a 3PL
• Rate limits: designing an integration that does not throttle