insonl
← journal

How to Ground Shopify Order-Status Replies in Fulfillment Data

date
21 November 2026
by
Insonl
read
7 min read

When a team wires generative AI to Shopify for AI order tracking with Shopify fulfillment data, reading only Order.displayFulfillmentStatus produces confident wrong answers. Even when an order is FULFILLED (all items fulfilled), a fulfilled shipment can still await carrier pickup; a PARTIALLY_FULFILLED order can have one shipment awaiting pickup while other items sit on hold at a second location.

Ground replies in Order, FulfillmentOrder, and Fulfillment with FulfillmentEvent records, and enforce explicit rules for partial fulfillment and stale tracking.

Drawing on Shopify’s third-party GraphQL Admin API docs (not an Insonl client), this post defines the snapshot to fetch, walks through a made-up payload, and flags API behaviors that mislead tracking bots.

Why order-level status alone produces wrong tracking replies

Shopify splits order state, planned work, and recorded milestones across three objects:

  1. Order summary (Order.displayFulfillmentStatus). Per Order and OrderDisplayFulfillmentStatus, this enum aggregates display state (UNFULFILLED, PARTIALLY_FULFILLED, FULFILLED, IN_PROGRESS, ON_HOLD, SCHEDULED, REQUEST_DECLINED, FULFILLMENT_NOT_REQUIRED, plus replaced legacy values). The Order docs direct detailed processing to FulfillmentOrder. Check cancelledAt and cancelReason first so a bot never reports progress on a canceled order.
  2. Planned work (FulfillmentOrder). Per FulfillmentOrder, Shopify creates fulfillment orders automatically after routing to group items for one location, exposing status (FulfillmentOrderStatus), requestStatus (FulfillmentOrderRequestStatus), fulfillAt, fulfillmentHolds, and each FulfillmentOrderLineItem’s totalQuantity and remainingQuantity (units still to be fulfilled).
  3. Fulfillments and events (Fulfillment and FulfillmentEvent). Per Fulfillment, one order can have multiple fulfillments when items ship separately or from different locations. In Shopify’s documented merchant-managed workflow (FulfillmentOrder), a Fulfillment is created after picking and packing—before courier pickup. FulfillmentStatus (SUCCESS, CANCELLED, ERROR, FAILURE) reflects the fulfillment record, not delivery. trackingInfo holds tracking identifiers (carrier, numbers, URLs), estimatedDeliveryAt is an estimate, and displayStatus, inTransitAt, deliveredAt, and Fulfillment.events (FulfillmentEvent) store recorded milestones and timestamps—because apps can also write events via fulfillmentEventCreate, events alone do not prove carrier provenance.

Fetch one grounded snapshot before generating a reply

Before replying—or updating CRM systems—a deterministic resolver should fetch one snapshot and compute counts and event age in code.

Question Shopify GraphQL fields Failure mode if skipped
Canceled? Order.cancelledAt, cancelReason, displayFulfillmentStatus Treating a canceled order as active.
What remains unfulfilled, and why? Order.fulfillmentOrders(displayable: true, first: N) → nodes / edges { node } (status, requestStatus, fulfillAt, fulfillmentHolds { reason displayReason }, lineItems(first: N) → nodes / edges { node { productTitle sku totalQuantity remainingQuantity } }) Reporting a partial shipment as complete.
What belongs to each active fulfillment? Order.fulfillments (select status, filter SUCCESS in code) → id, name, status, displayStatus, createdAt, inTransitAt, deliveredAt, estimatedDeliveryAt, fulfillmentLineItems(first: N) → nodes / edges { node { quantity lineItem { title sku } } }, trackingInfo { company number url } Listing canceled fulfillments as active or dropping line-item quantities per fulfillment (one fulfillment can span multiple packages).
What was the last recorded milestone? Fulfillment.events(sortKey: HAPPENED_AT, reverse: true, first: N) → nodes / edges { node { status happenedAt createdAt city province country message estimatedDeliveryAt } } Calling LABEL_PURCHASED “in transit” or sorting by ingestion time.

Three normalization rules:

  • Paginate connections before counting. fulfillmentOrders, lineItems, fulfillmentLineItems, and events are paginated connections (nodes or edges { node }); pass page sizes (first) and follow cursors (after) before claiming complete counts.
  • Sort events by HAPPENED_AT, not CREATED_AT. FulfillmentEventSortKeys supports CREATED_AT, HAPPENED_AT, and ID. Measure age from happenedAt (event time), not createdAt (storage time).
  • Map hold reasons to customer-safe copy. FulfillmentHold returns reason (FulfillmentHoldReason: e.g. AWAITING_PAYMENT, INCORRECT_ADDRESS, INVENTORY_OUT_OF_STOCK, HIGH_RISK_OF_FRAUD), displayReason, and reasonNotes. Never echo reasonNotes or HIGH_RISK_OF_FRAUD; map enum values to approved copy and escalate sensitive holds.

Worked example: a partially fulfilled order with stale tracking

(Illustrative example—not a real store, order, scan, or Insonl client. All IDs, SKUs, tracking numbers, URLs, and timestamps are made up.)

Suppose an authenticated shopper asks “Where is my order #4821?” at 2026-11-21T08:30:00Z, returning this trimmed GraphQL data payload:

{
  "data": {
    "order": {
      "name": "#4821",
      "cancelledAt": null,
      "displayFulfillmentStatus": "PARTIALLY_FULFILLED",
      "fulfillmentOrders": {
        "nodes": [
          {
            "id": "gid://shopify/FulfillmentOrder/7001",
            "status": "CLOSED",
            "fulfillmentHolds": [],
            "lineItems": { "nodes": [{ "productTitle": "Gooseneck Kettle", "sku": "SKU-KET-01", "totalQuantity": 1, "remainingQuantity": 0 }] }
          },
          {
            "id": "gid://shopify/FulfillmentOrder/7002",
            "status": "ON_HOLD",
            "fulfillmentHolds": [{ "reason": "INVENTORY_OUT_OF_STOCK", "displayReason": "Inventory out of stock" }],
            "fulfillments": { "nodes": [] },
            "lineItems": { "nodes": [{ "productTitle": "Paper Filters 100-Pack", "sku": "SKU-FLT-02", "totalQuantity": 1, "remainingQuantity": 1 }] }
          }
        ]
      },
      "fulfillments": [
        {
          "id": "gid://shopify/Fulfillment/8001",
          "name": "#4821-F1",
          "status": "SUCCESS",
          "displayStatus": "LABEL_PURCHASED",
          "createdAt": "2026-11-17T03:10:00Z",
          "inTransitAt": null,
          "estimatedDeliveryAt": null,
          "fulfillmentLineItems": { "nodes": [{ "quantity": 1, "lineItem": { "title": "Gooseneck Kettle", "sku": "SKU-KET-01" } }] },
          "trackingInfo": [{ "company": "DHL Express", "number": "0000000000", "url": "https://example.invalid/track/0000000000" }],
          "events": { "nodes": [{ "status": "LABEL_PURCHASED", "happenedAt": "2026-11-17T03:12:00Z", "createdAt": "2026-11-17T03:12:04Z" }] }
        }
      ]
    }
  }
}

A naive bot reads status: "SUCCESS" and replies “Your order #4821 has shipped and is on its way.” The records confirm neither pickup nor transit and omit the unfulfilled item.

The resolver classifies two states:

  • Fulfillment #4821-F1 (gid://shopify/Fulfillment/8001, Gooseneck Kettle, qty 1): displayStatus is LABEL_PURCHASED, inTransitAt and estimatedDeliveryAt are null, and the latest event (LABEL_PURCHASED) happened at 2026-11-17T03:12:00Z. With no CARRIER_PICKED_UP or IN_TRANSIT event past the resolver’s configured staleness window, it flags stale_pre_transit.
  • Fulfillment order 7002 (Paper Filters 100-Pack, remainingQuantity: 1): status is ON_HOLD (INVENTORY_OUT_OF_STOCK) with an empty fulfillments list—one unit is still on hold and unfulfilled.

Grounded reply (include the closing escalation line only after the handoff write succeeds):

Order #4821 is split into two parts:

  1. Gooseneck Kettle (1): A DHL Express label (0000000000) was created on 17 Nov 2026, with no pickup or transit event recorded since 2026-11-17T03:12:00Z and no estimated delivery date on file (https://example.invalid/track/0000000000).
  2. Paper Filters 100-Pack (1): Not fulfilled yet; this item is on hold because it is out of stock.

Because the first fulfillment has no recorded pickup event since 17 Nov and the second is on hold, I have flagged your order for our fulfillment team.

Drop that final line if the handoff fails and give a support contact instead. Once confirmed, pass Fulfillment.id (gid://shopify/Fulfillment/8001), the hold code, and last happenedAt following what an AI assistant should pass to a Zendesk agent.

Reply rules for split shipments, holds, and stale tracking

Enforce state-to-claim rules in code:

  • Split shipments (PARTIALLY_FULFILLED or multiple active fulfillments): Multiple FulfillmentOrder records do not prove multiple shipments; describe shipment groups from active Fulfillment records alongside any FulfillmentOrderLineItem with remainingQuantity > 0. For a SCHEDULED fulfillment order, a populated fulfillAt tells you when it becomes eligible for fulfillment (fulfillAt is null on pre-orders without a release date). If a fulfillment service sets requestStatus: REJECTED or status: INCOMPLETE, escalate instead of promising dispatch.
  • Pre-transit statuses and inTransitAt: Report only the milestone the available records support. LABEL_PURCHASED and LABEL_PRINTED indicate label steps, not transit; per FulfillmentEventStatus, CONFIRMED is the default when no other information is available and establishes neither packing nor labeling. Likewise, a null inTransitAt cannot override an event recording pickup, transit, or delivery.
  • Missing or stale tracking updates: Per FulfillmentTrackingInfo, Shopify builds clickable URLs for many carriers but automatically updates Admin shipment_status for only a listed subset (21 carriers, including DHL Express, FedEx, UPS, and USPS). When Fulfillment.events is empty, say no tracking updates are available in Shopify, share a verified link if present, and check the carrier directly or escalate.
  • Delivery exceptions: Report event exceptions (DELAYED, ATTEMPTED_DELIVERY, FAILURE on FulfillmentEventStatus) with happenedAt and location fields only from the event that recorded that milestone. NOT_DELIVERED, LABEL_VOIDED, and CANCELED exist only on FulfillmentDisplayStatus—when only a display status exists, report it without borrowing a timestamp or location, omit any ETA absent from estimatedDeliveryAt, and escalate under the stop boundaries in AI customer enquiry automation.

Shopify API constraints that break tracking assistants

Four documented GraphQL Admin API behaviors break tracking replies:

  1. 60-day default order window. Per Order and Shopify API access scopes, only orders from the last 60 days are accessible by default. Older orders require read_all_orders alongside read_orders or write_orders: Partner-organization apps need Shopify approval, whereas apps created under a merchant organization for its own stores can declare it without that approval.
  2. Scope-filtered fulfillment orders. Per FulfillmentOrder, Order.fulfillmentOrders returns only records matching the app’s scopes (read_merchant_managed_fulfillment_orders, read_third_party_fulfillment_orders, read_assigned_fulfillment_orders, or read_marketplace_fulfillment_orders). A general order-management app can miss fulfillment orders assigned to another fulfillment service without the relevant third-party scope; a fulfillment service app reads its own assigned locations via the assigned scope.
  3. Hidden fulfillment orders and canceled fulfillments. Pass displayable: true on Order.fulfillmentOrders to exclude records closed after moves or merges, and filter out CANCELLED, ERROR, and FAILURE fulfillments in code—Order.fulfillmentsCount includes canceled ones.
  4. Tracking URL fallback and tax-only origin addresses. Per FulfillmentTrackingInfo, Shopify uses an explicit url first, then builds one for a recognized company name; only otherwise may it guess when the number matches a recognized format, and similar formats can yield an invalid URL. Per Fulfillment, originAddress is for tax calculation; read FulfillmentOrder.assignedLocation for the fulfillment location’s address.

Audit your order-status workflow before connecting an LLM

Insonl is a Ho Chi Minh City engineering studio building CRM integrations and generative AI systems. If your assistant relies on top-level Shopify statuses or guesses dates on split shipments, start with our free AI workflow audit.

The audit is free; work after it is charged separately.

Sources