Query `inventoryItem(id: $inventoryItemId)` or `productVariant.inventoryItem` to retrieve the inventory item ID for the variant you want to update
Fetch the current `on_hand` quantities per location via `inventoryLevel.quantities(names: ["on_hand"])` on the inventory item to get current values for compare-and-swap
Call `inventorySetQuantities(input: { name: "on_hand", reason: "correction", quantities: [{ inventoryItemId: $id, locationId: $locationId, quantity: 50, compareQuantity: 45 }] })` — the `compareQuantity` acts as an optimistic lock to prevent overwriting concurrent updates
Check `inventorySetQuantitiesPayload.userErrors`; a `compareQuantity` mismatch error means another process updated the inventory between your read and write — re-fetch and retry
Use `reason` values such as `correction`, `received`, or `damaged` to annotate the reason for the quantity change; this appears in the inventory history log
For bulk updates across many variants and locations, batch multiple `quantities` entries in a single mutation call rather than making one call per variant
Known gotchas
inventorySetOnHandQuantities is deprecated — use inventorySetQuantities with `name: "on_hand"` instead; the old mutation will eventually be removed
The `compareQuantity` field (and the deprecated `ignoreCompareQuantity`) will be replaced by `changeFromQuantity` in future API versions per the Shopify changelog — adopt the new field when targeting 2025-10+
inventorySetQuantities sets absolute quantities and is intended for systems that are the source of truth (e.g., a WMS); for relative adjustments (increment/decrement), use inventoryAdjustQuantities instead to avoid overwriting concurrent changes
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp