insonl
← journal

How to Answer Shopify Stock Questions With Live Inventory

date
21 November 2026
by
Insonl
read
7 min read

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:

  1. Product and variant (Product, ProductVariant). Per Product and ProductVariant, Product.totalInventory, ProductVariant.inventoryQuantity, and ProductVariant.availableForSale collapse locations into one value. Even ProductVariant.sellableOnlineQuantity omits customer-location rules (markets, shipping zones) and is not total available inventory.
  2. Physical item (InventoryItem). Per InventoryItem, each variant maps 1:1 to an InventoryItem (sku, tracked, duplicateSkuCount, requiresShipping). If tracked is false, Shopify does not track stock; when ProductVariant.inventoryPolicy (ProductVariantInventoryPolicy) is CONTINUE, 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.
  3. Location ledger (InventoryLevel, InventoryQuantity). Per InventoryLevel, InventoryQuantity, and Apps in inventory management, each level pairs one InventoryItem with one Location across eight states via quantities(names: [...]). Seven (incoming, available, committed, reserved, damaged, safety_stock, quality_control) are mutually exclusive; on_hand sums the six physical states and excludes incoming:
    • 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 into available.
  4. Fulfillment site (Location). Per Location, fulfillsOnlineOrders indicates 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, while localPickupSettingsV2 exposes 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 while pageInfo.hasNextPage is true and pass pageInfo.endCursor as after on both productVariants and inventoryLevels before reporting zero stock or totals.
  • Separate Shopify status from merchant visibility rules. DRAFT and ARCHIVED products are unavailable on sales channels, while UNLISTED products remain reachable by direct link and behave like ACTIVE items in cart and checkout—withholding UNLISTED products from open chat is a merchant policy rule, alongside checking publishedOnPublication(publicationId: $pubId) for the target channel.
  • Assert active flags and stop on collisions. Require active InventoryLevel and Location (isActive: true). Confirm options if duplicateSkuCount > 0 or multiple variants match; check component stock if requiresComponents is true.

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: 2 available at Main Warehouse (0 at East 3PL), short of 3.
  • Local pickup: 1 available at Downtown Retail, where DeliveryLocalPickupSettings sets pickupTime: 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), and incoming (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; committed covers 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). When available <= 0 and inventoryPolicy is CONTINUE, the variant permits backorders rather than proving shelf stock—qualify whether the shopper can order through the relevant channel and escalate lead-time questions. When tracked is false, state that Shopify does not track live counts and route quantity checks to staff.
  • Incoming stock and destination rules. Never add incoming units to available or invent an ETA. Qualify shipping eligibility until checkout validates rates and markets.
  • 3PL sync lag and bundles. For isFulfillmentService: true locations, per fulfillmentServiceCreate and the callback URL changelog, fetch_stock polling applies only when a callbackUrl is configured with inventoryManagement: true (callbackUrl is optional as of API version 2026-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

  1. Five states do not emit webhooks. Per Apps in inventory management, changes to committed, reserved, damaged, safety_stock, and quality_control emit no webhooks; query Admin GraphQL live instead of relying on a webhook-only cache.
  2. Inactive inventory levels can hold quantities. Per Manage inventory quantities and states, from API version 2026-04, quantity mutations can create an inactive InventoryLevel (isActive: false) whose units stay unsellable until activated. Keep includeInactive false and assert isActive: true.
  3. Default locations queries omit fulfillment-service sites. Per locations, pass includeLegacy: true (or query shop.fulfillmentServices) to include them. Ignore legacy Location.shipsInventory—all locations with valid addresses can now ship—and pair fulfillsOnlineOrders with shipping configuration.
  4. Scopes and deprecated scheduled changes. Per Shopify API access scopes and object docs: Product/ProductVariant need read_products; InventoryLevel/InventoryQuantity need read_inventory; Location needs read_locations (or read_inventory/read_markets_home); localPickupSettingsV2 needs locations, shipping, or manage_delivery_settings. InventoryLevel.scheduledChanges is deprecated and inventorySetScheduledChanges is removed in API version 2026-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