Keeping inventory in sync with another system

Decide what quantity each system owns

Before connecting systems, decide what a quantity means and which system is responsible for keeping it accurate. Shopify models inventory by state and location, so an external number should not be treated as a generic stock total.

Available inventory is the quantity a merchant can sell; it excludes committed inventory and incoming transfers. On-hand inventory is the total physically present at a location, including available, committed, reserved, damaged, safety-stock, and quality-control quantities. Incoming inventory isn't available to sell until it has been received and its state changed to available. Shopify’s documented inventory states are mutually exclusive, so distinguish which state an external quantity represents before syncing it.

Write down the ownership decision for each quantity before choosing a sync direction. For example, your team might decide that one system owns available quantities while another records incoming stock; that is an integration policy, not a Shopify rule. Also decide what happens if both systems have a change to apply: choose an authority for conflicts, define whether a change is rejected or reviewed, and document how the decision is recorded. Make the rules specific enough that someone investigating a mismatch can tell which system’s value should be retained.

Map products, locations, and tracking

A product and location crosswalk gives the integration a clear target for every quantity it reads or changes. Match each external item to the corresponding Shopify product or variant, and map each external stockholding point to the Shopify location your team intends to use. Record how unmapped products and locations will be handled rather than silently sending updates to a default destination.

An inventory level represents inventory quantities for a product at a specific location, and Shopify’s inventoryLevel and inventoryItem queries can retrieve quantities in the documented inventory states. Shopify inventory tracking must be set up for a product before its inventory levels can be viewed or adjusted. Confirm tracking is enabled for every product in scope before testing reads or writes; if a product is missing from an integration view, treat tracking status as a setup check rather than assuming its quantity is zero.

Check app-location allocation as part of the mapping review. When an inventory app tracks a product’s quantity, that quantity is allocated only to the app’s location, and product location assignments can be changed. Agree on which location the app should use, verify the product’s assignment, and make sure the other system’s location mapping reflects that choice. Keep a record of the mapping so future changes to assignments do not leave the integration pointing at an unintended location.

Choose the Shopify operation that matches the change

Once quantity ownership and mappings are clear, choose a Shopify operation based on whether the external system is reporting a change, a target quantity, or a movement between states. Query the relevant state and location first, then compare it with the external record using the sync policy your team has chosen.

The inventoryAdjustQuantities mutation adjusts an inventory quantity for a given product, state, or location by a given delta. Use that operation when the external event represents a known increase or decrease, and preserve the event’s meaning in your integration’s records. The inventorySetQuantities mutation sets a value for on-hand or available inventory. Use a set operation only when the source is intended to provide the authoritative target value; otherwise, a stale target could replace a newer quantity.

The inventoryMoveQuantities mutation moves quantities between available and specified unavailable states, or between unavailable states. Select it when the event is a reclassification or movement between supported states rather than a change to the total. You can't use the Admin API to adjust or move inventory quantities in the committed state. For adjustments, sets, or moves, the referenceDocumentUri input can record the system and document that initiated the operation, which helps your team connect a Shopify change to its source record.

• Use a delta when the source reports an increase or decrease.
• Use a set when the source is authorized to declare the target on-hand or available quantity.
• Use a move when stock is changing between supported available or unavailable states.
• Do not design an Admin API write for committed inventory; let the relevant Shopify action manage that state.

Plan updates around webhook coverage

Treat webhook handling as part of the sync design, not as proof that every inventory change will generate an event. Shopify says apps can subscribe to inventory-related webhooks. Decide which topics the app needs, and define what the integration does after it receives a relevant notification.

Changes to committed, reserved, damaged, safety-stock, and quality-control states do not trigger webhooks. That makes a webhook-only strategy incomplete if the integration must account for those states. Shopify also manages committed inventory itself: inventory is committed when a placed order hasn’t been fulfilled, and committed quantities change through actions such as creating and fulfilling orders rather than through the Admin API.

Set an explicit policy for updates that arrive close together, repeated updates, and a missed or unprocessed notification. For example, decide when to query Shopify again, how to compare that result with the external system, and whether a mismatch should be automatically resolved or sent for review. These are integration policies, not documented Shopify conflict rules. Keep notification processing separate from the decision about which system owns a quantity, so receiving an event does not automatically make that event’s value authoritative.

• Subscribe to the inventory item and inventory level topics relevant to the integration.
• Document which inventory states are not covered by webhook changes.
• Define how to re-query, compare, and escalate when an update is missed or conflicts with another change.

Reconcile records against physical counts

Build reconciliation into normal operations so the integration has a way to detect divergence that event handling did not resolve. Shopify recommends updating inventory records after the count is completed and verified. Agree on who verifies a count and which system is allowed to apply the corrected quantity.

Use a repeatable checklist: select the product and location, compare the verified physical count with the corresponding records, investigate significant discrepancies, and update the records only after the count is verified. Record the chosen quantity, its inventory state, its location, and the source document so a later review can distinguish a correction from an ordinary stock movement. If the discrepancy is not resolved, keep it visible for investigation instead of repeatedly overwriting one system from the other.

Shopify lets merchants view a product’s inventory history for up to 180 days when inventory tracking is enabled. Use the available history as one source when investigating a discrepancy, alongside the records kept by the other system and the team’s count documentation. Reconciliation should confirm that the corrected value is being applied to the intended product, location, and state; it should not become an unplanned rule that every system always overwrites Shopify.

• Compare physical counts with records for the same product, location, and inventory state.
• Investigate significant discrepancies and verify the count before changing records.
• Record the correction’s source and review unresolved differences instead of repeatedly overwriting values.