Wiring generative AI to a Shopify inventory lookup for a support chatbot fails when the bot reads a single variant count. A variant can show stock store-wide while parcel warehouses are short, pickup stores lack units, or shelf stock is committed.
Ground replies in ProductVariant, InventoryItem, InventoryLevel, and Location, separate sellable units from non-sellable states, and qualify answers when channel rules, checkout timing, or sync lag block a guarantee. Using Shopify’s third-party docs (not an Insonl client), this post maps the model, walks through a made-up payload, and sets qualification rules. For post-purchase shipment checks, see how to ground Shopify order-status replies in fulfillment data.
Why aggregate counts and flat stock buckets mislead bots
Per Manage inventory quantities and states, Shopify splits catalog data, SKU tracking, per-location ledgers, and fulfillment sites across four objects:
- Product and variant (
Product,ProductVariant). Per Product and ProductVariant,Product.totalInventory,ProductVariant.inventoryQuantity, andProductVariant.availableForSalecollapse locations into one value. EvenProductVariant.sellableOnlineQuantityomits customer-location rules (markets, shipping zones) and is not total available inventory. - Physical item (
InventoryItem). Per InventoryItem, each variant maps 1:1 to anInventoryItem(sku,tracked,duplicateSkuCount,requiresShipping). Iftrackedisfalse, Shopify does not track stock; whenProductVariant.inventoryPolicy(ProductVariantInventoryPolicy) isCONTINUE, the variant permits backorders after stock reaches zero, so the assistant must qualify whether the shopper can order through the relevant channel rather than assuming shelf stock. - Location ledger (
InventoryLevel,InventoryQuantity). Per InventoryLevel, InventoryQuantity, and Apps in inventory management, each level pairs oneInventoryItemwith oneLocationacross eight states viaquantities(names: [...]). Seven (incoming,available,committed,reserved,damaged,safety_stock,quality_control) are mutually exclusive;on_handsums the six physical states and excludesincoming:available: uncommitted sellable units at that location (excluding incoming transfers)—the only bucket safe to quote as buyable.committed: units allocated to unfulfilled orders, draft-order reservations, or transfers and shipments marked ready to ship.reserved,damaged,safety_stock,quality_control: physical units held for holds/3PL, damage, buffers, or inspection (Unavailable in admin).incoming: units in transit—unsellable until received intoavailable.
- Fulfillment site (
Location). Per Location,fulfillsOnlineOrdersindicates online fulfillment eligibility overall (shipping, local delivery, or local pickup). Per Shopify’s pickup-in-store setup guide, pickup locations must fulfill online orders (fulfillsOnlineOrders: true) and can be restricted to in-store pickup via shipping configuration, whilelocalPickupSettingsV2exposes pickup readiness.
Fetch one location-aware inventory snapshot
Before replying or escalating to CRM systems, run a deterministic resolver to match the variant and sum eligible available counts.
| Check | Shopify GraphQL fields | Failure mode if skipped |
|---|---|---|
| Sellable on channel? | productVariants(first: N, after: $cursor, query: "sku:...") → nodes { id displayName sku availableForSale inventoryPolicy inventoryQuantity sellableOnlineQuantity requiresComponents publishedOnPublication(publicationId: $pubId) product { status tracksInventory } } pageInfo { hasNextPage endCursor } |
Quoting DRAFT/ARCHIVED (ProductStatus), assuming ACTIVE is published, exposing UNLISTED against policy (Unlisted product status), or missing bundles (requiresComponents: true). |
| Tracked SKU? | ProductVariant.inventoryItem → id sku tracked duplicateSkuCount |
Reporting 0 on untracked items or matching the wrong variant when duplicateSkuCount > 0. |
| Per-location states? | InventoryItem.inventoryLevels(first: N, after: $cursor) → nodes { id isActive updatedAt quantities(names: ["available", "on_hand", "committed", "incoming", "reserved", "damaged", "safety_stock", "quality_control"]) { name quantity updatedAt } } pageInfo { hasNextPage endCursor } |
Counting inactive levels (isActive: false), truncating locations, or quoting on_hand as sellable. |
| Shipping or pickup? | InventoryLevel.location → id name isActive fulfillsOnlineOrders isFulfillmentService localPickupSettingsV2 { pickupTime instructions } |
Mixing pickup-only and parcel stock or promising pickup without pickup settings. |
Three normalization rules:
- Paginate with
pageInfo. Per Paginating results with GraphQL, loop whilepageInfo.hasNextPageistrueand passpageInfo.endCursorasafteron bothproductVariantsandinventoryLevelsbefore reporting zero stock or totals. - Separate Shopify status from merchant visibility rules.
DRAFTandARCHIVEDproducts are unavailable on sales channels, whileUNLISTEDproducts remain reachable by direct link and behave likeACTIVEitems in cart and checkout—withholdingUNLISTEDproducts from open chat is a merchant policy rule, alongside checkingpublishedOnPublication(publicationId: $pubId)for the target channel. - Assert active flags and stop on collisions. Require active
InventoryLevelandLocation(isActive: true). Confirm options ifduplicateSkuCount > 0or multiple variants match; check component stock ifrequiresComponentsistrue.
Worked example: one variant across three locations
(Illustrative example—not a real store, SKU, location, or Insonl client; IDs, counts, and timestamps are made up. Here Downtown Retail is excluded from parcel delivery in shipping configuration and restricted to pickup, with store transfers disabled.)
At 2026-11-21T09:30:00Z, a shopper asks: “Do you have 3 Slate 12oz travel mugs to order online or pick up downtown?” Querying productVariants for sku:SKU-MUG-12OZ returns:
{
"data": {
"productVariants": {
"nodes": [{
"id": "gid://shopify/ProductVariant/9001",
"displayName": "Insulated Travel Mug - Slate 12oz",
"sku": "SKU-MUG-12OZ",
"availableForSale": true,
"inventoryPolicy": "DENY",
"inventoryQuantity": 3,
"sellableOnlineQuantity": 3,
"requiresComponents": false,
"publishedOnPublication": true,
"product": { "status": "ACTIVE", "tracksInventory": true },
"inventoryItem": {
"id": "gid://shopify/InventoryItem/9101",
"tracked": true,
"duplicateSkuCount": 0,
"inventoryLevels": {
"nodes": [
{
"id": "gid://shopify/InventoryLevel/5001?inventory_item_id=9101",
"isActive": true,
"location": { "id": "gid://shopify/Location/6001", "name": "Main Warehouse", "isActive": true, "fulfillsOnlineOrders": true, "isFulfillmentService": false, "localPickupSettingsV2": null },
"quantities": [{"name":"available","quantity":2},{"name":"committed","quantity":5},{"name":"safety_stock","quantity":3},{"name":"on_hand","quantity":10},{"name":"incoming","quantity":20}]
},
{
"id": "gid://shopify/InventoryLevel/5002?inventory_item_id=9101",
"isActive": true,
"location": { "id": "gid://shopify/Location/6002", "name": "Downtown Retail", "isActive": true, "fulfillsOnlineOrders": true, "isFulfillmentService": false, "localPickupSettingsV2": {"pickupTime":"TWO_HOURS"} },
"quantities": [{"name":"available","quantity":1},{"name":"reserved","quantity":2},{"name":"on_hand","quantity":3},{"name":"incoming","quantity":0}]
},
{
"id": "gid://shopify/InventoryLevel/5003?inventory_item_id=9101",
"isActive": true,
"location": { "id": "gid://shopify/Location/6003", "name": "East 3PL", "isActive": true, "fulfillsOnlineOrders": true, "isFulfillmentService": true, "localPickupSettingsV2": null },
"quantities": [{"name":"available","quantity":0},{"name":"damaged","quantity":4},{"name":"on_hand","quantity":4},{"name":"incoming","quantity":0}]
}
],
"pageInfo": { "hasNextPage": false, "endCursor": "eyJsYXN0X2lkIjo1MDAzfQ==" }
}
}
}],
"pageInfo": { "hasNextPage": false, "endCursor": "eyJsYXN0X2lkIjo5MDAxfQ==" }
}
}
}
A naive bot reads sellableOnlineQuantity: 3 (or sums on_hand to 17) and answers “Yes, 3 in stock to ship.” That fails at checkout: Downtown Retail has fulfillsOnlineOrders: true for pickup only and is excluded from parcel delivery in shipping configuration, while East 3PL has 0 available (4 units are damaged).
Resolver output:
- Online parcel shipping:
2availableatMain Warehouse(0atEast 3PL), short of3. - Local pickup:
1availableatDowntown Retail, where DeliveryLocalPickupSettings setspickupTime: TWO_HOURS(per DeliveryLocalPickupTime, usually ready in 2 hours). With store transfers disabled, pickup cannot pull the warehouse’s 2 units—per Shopify’s pickup store transfers guide, enabling store transfers can make inventory from other locations available for pickup with an adjusted pickup estimate. - Excluded:
committed(5),safety_stock(3),reserved(2),damaged(4), andincoming(20)—no restock date promised.
Grounded reply:
As of
09:30 UTC, we do not have 3 units of Insulated Travel Mug - Slate 12oz (SKU-MUG-12OZ) in one option:
- Online shipping: 2 units currently available (subject to shipping eligibility and checkout confirmation).
- Downtown Retail pickup: 1 unit currently available—usually ready in 2 hours once confirmed.
This lookup cannot reserve stock, so low counts can change before checkout. I do not have a confirmed restock date—I can pass transfer or bulk-order questions to our support team.
Never expose damaged, safety_stock, or committed counts. On escalation, pass ProductVariant.id, sku, quantity, and location IDs per Zendesk AI handoff ticket fields.
When the assistant should qualify instead of promising stock
Enforce qualification rules in code:
- Low stock and checkout holds. A live lookup cannot hold inventory. Per Shopify Checkout, checkout holds inventory only when the customer submits payment information and releases the hold if payment fails;
committedcovers unfulfilled orders, draft-order reservations, and transfers or shipments marked ready to ship. Below a merchant-set threshold, state the lookup time and qualify until checkout confirms. - Backorders (
CONTINUE) and untracked items (tracked: false). Whenavailable <= 0andinventoryPolicyisCONTINUE, the variant permits backorders rather than proving shelf stock—qualify whether the shopper can order through the relevant channel and escalate lead-time questions. Whentrackedisfalse, state that Shopify does not track live counts and route quantity checks to staff. - Incoming stock and destination rules. Never add
incomingunits toavailableor invent an ETA. Qualify shipping eligibility until checkout validates rates and markets. - 3PL sync lag and bundles. For
isFulfillmentService: truelocations, per fulfillmentServiceCreate and the callback URL changelog,fetch_stockpolling applies only when acallbackUrlis configured withinventoryManagement: true(callbackUrlis optional as of API version2026-01; services without one submit inventory updates via the API), so counts can trail warehouse reality. Bundles (requiresComponents: true) require component-level checks.
Shopify API constraints that break inventory assistants
- Five states do not emit webhooks. Per Apps in inventory management, changes to
committed,reserved,damaged,safety_stock, andquality_controlemit no webhooks; query Admin GraphQL live instead of relying on a webhook-only cache. - Inactive inventory levels can hold quantities. Per Manage inventory quantities and states, from API version
2026-04, quantity mutations can create an inactiveInventoryLevel(isActive: false) whose units stay unsellable until activated. KeepincludeInactivefalse and assertisActive: true. - Default
locationsqueries omit fulfillment-service sites. Per locations, passincludeLegacy: true(or queryshop.fulfillmentServices) to include them. Ignore legacyLocation.shipsInventory—all locations with valid addresses can now ship—and pairfulfillsOnlineOrderswith shipping configuration. - Scopes and deprecated scheduled changes. Per Shopify API access scopes and object docs:
Product/ProductVariantneedread_products;InventoryLevel/InventoryQuantityneedread_inventory;Locationneedsread_locations(orread_inventory/read_markets_home);localPickupSettingsV2needslocations,shipping, ormanage_delivery_settings.InventoryLevel.scheduledChangesis deprecated andinventorySetScheduledChangesis removed in API version2026-07—never use it for restock dates.
Audit your inventory-lookup workflow before connecting an LLM
Insonl is a Ho Chi Minh City engineering studio building CRM integrations and generative AI systems. If your assistant reads aggregate Shopify counts without state and location checks, start with our free AI workflow audit.
The audit is free; work after it is charged separately.
Sources
- Shopify Developer Docs (third-party docs): InventoryLevel · InventoryItem · InventoryQuantity · Location · DeliveryLocalPickupSettings · DeliveryLocalPickupTime · Product · ProductStatus · ProductVariant · ProductVariantInventoryPolicy · productVariants · locations · fulfillmentServiceCreate · Apps in inventory management · Manage inventory quantities and states · Unlisted product status · Paginating results with GraphQL · Access scopes · Callback URL changelog
- Shopify Help Center (third-party docs): Migrating a retail store (Step 12) · Pickup in store (Store transfers) · Shopify Checkout
- Insonl: CRM Solutions · Generative AI · Free AI workflow audit · Shopify Order-Status Replies · Zendesk AI Handoff Ticket Fields
