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:
- 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). TheOrderdocs direct detailed processing toFulfillmentOrder. CheckcancelledAtandcancelReasonfirst so a bot never reports progress on a canceled order. - Planned work (
FulfillmentOrder). Per FulfillmentOrder, Shopify creates fulfillment orders automatically after routing to group items for one location, exposingstatus(FulfillmentOrderStatus),requestStatus(FulfillmentOrderRequestStatus),fulfillAt,fulfillmentHolds, and each FulfillmentOrderLineItem’stotalQuantityandremainingQuantity(units still to be fulfilled). - Fulfillments and events (
FulfillmentandFulfillmentEvent). Per Fulfillment, one order can have multiple fulfillments when items ship separately or from different locations. In Shopify’s documented merchant-managed workflow (FulfillmentOrder), aFulfillmentis created after picking and packing—before courier pickup. FulfillmentStatus (SUCCESS,CANCELLED,ERROR,FAILURE) reflects the fulfillment record, not delivery.trackingInfoholds tracking identifiers (carrier, numbers, URLs),estimatedDeliveryAtis an estimate, anddisplayStatus,inTransitAt,deliveredAt, andFulfillment.events(FulfillmentEvent) store recorded milestones and timestamps—because apps can also write events viafulfillmentEventCreate, 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, andeventsare paginated connections (nodesoredges { node }); pass page sizes (first) and follow cursors (after) before claiming complete counts. - Sort events by
HAPPENED_AT, notCREATED_AT. FulfillmentEventSortKeys supportsCREATED_AT,HAPPENED_AT, andID. Measure age fromhappenedAt(event time), notcreatedAt(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, andreasonNotes. Never echoreasonNotesorHIGH_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, qty1):displayStatusisLABEL_PURCHASED,inTransitAtandestimatedDeliveryAtarenull, and the latest event (LABEL_PURCHASED) happened at2026-11-17T03:12:00Z. With noCARRIER_PICKED_UPorIN_TRANSITevent past the resolver’s configured staleness window, it flagsstale_pre_transit. - Fulfillment order
7002(Paper Filters 100-Pack,remainingQuantity: 1):statusisON_HOLD(INVENTORY_OUT_OF_STOCK) with an emptyfulfillmentslist—one unit is still on hold and unfulfilled.
Grounded reply (include the closing escalation line only after the handoff write succeeds):
Order
#4821is split into two parts:
- Gooseneck Kettle (1): A DHL Express label (
0000000000) was created on 17 Nov 2026, with no pickup or transit event recorded since2026-11-17T03:12:00Zand no estimated delivery date on file (https://example.invalid/track/0000000000).- 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_FULFILLEDor multiple active fulfillments): MultipleFulfillmentOrderrecords do not prove multiple shipments; describe shipment groups from activeFulfillmentrecords alongside anyFulfillmentOrderLineItemwithremainingQuantity > 0. For aSCHEDULEDfulfillment order, a populatedfulfillAttells you when it becomes eligible for fulfillment (fulfillAtisnullon pre-orders without a release date). If a fulfillment service setsrequestStatus: REJECTEDorstatus: INCOMPLETE, escalate instead of promising dispatch. - Pre-transit statuses and
inTransitAt: Report only the milestone the available records support.LABEL_PURCHASEDandLABEL_PRINTEDindicate label steps, not transit; per FulfillmentEventStatus,CONFIRMEDis the default when no other information is available and establishes neither packing nor labeling. Likewise, anullinTransitAtcannot 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_statusfor only a listed subset (21 carriers, including DHL Express, FedEx, UPS, and USPS). WhenFulfillment.eventsis 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,FAILUREon FulfillmentEventStatus) withhappenedAtand location fields only from the event that recorded that milestone.NOT_DELIVERED,LABEL_VOIDED, andCANCELEDexist only on FulfillmentDisplayStatus—when only a display status exists, report it without borrowing a timestamp or location, omit any ETA absent fromestimatedDeliveryAt, 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:
- 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_ordersalongsideread_ordersorwrite_orders: Partner-organization apps need Shopify approval, whereas apps created under a merchant organization for its own stores can declare it without that approval. - Scope-filtered fulfillment orders. Per FulfillmentOrder,
Order.fulfillmentOrdersreturns only records matching the app’s scopes (read_merchant_managed_fulfillment_orders,read_third_party_fulfillment_orders,read_assigned_fulfillment_orders, orread_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. - Hidden fulfillment orders and canceled fulfillments. Pass
displayable: trueonOrder.fulfillmentOrdersto exclude records closed after moves or merges, and filter outCANCELLED,ERROR, andFAILUREfulfillments in code—Order.fulfillmentsCountincludes canceled ones. - Tracking URL fallback and tax-only origin addresses. Per FulfillmentTrackingInfo, Shopify uses an explicit
urlfirst, then builds one for a recognizedcompanyname; only otherwise may it guess when the number matches a recognized format, and similar formats can yield an invalid URL. Per Fulfillment,originAddressis for tax calculation; readFulfillmentOrder.assignedLocationfor 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
- Shopify Developer Docs (third-party docs), Order: https://shopify.dev/docs/api/admin-graphql/latest/objects/Order
- Shopify Developer Docs (third-party docs), OrderDisplayFulfillmentStatus: https://shopify.dev/docs/api/admin-graphql/latest/enums/OrderDisplayFulfillmentStatus
- Shopify Developer Docs (third-party docs), FulfillmentOrder: https://shopify.dev/docs/api/admin-graphql/latest/objects/FulfillmentOrder
- Shopify Developer Docs (third-party docs), FulfillmentOrderStatus: https://shopify.dev/docs/api/admin-graphql/latest/enums/FulfillmentOrderStatus
- Shopify Developer Docs (third-party docs), FulfillmentOrderRequestStatus: https://shopify.dev/docs/api/admin-graphql/latest/enums/FulfillmentOrderRequestStatus
- Shopify Developer Docs (third-party docs), FulfillmentOrderLineItem: https://shopify.dev/docs/api/admin-graphql/latest/objects/FulfillmentOrderLineItem
- Shopify Developer Docs (third-party docs), FulfillmentHold: https://shopify.dev/docs/api/admin-graphql/latest/objects/FulfillmentHold
- Shopify Developer Docs (third-party docs), FulfillmentHoldReason: https://shopify.dev/docs/api/admin-graphql/latest/enums/FulfillmentHoldReason
- Shopify Developer Docs (third-party docs), Fulfillment: https://shopify.dev/docs/api/admin-graphql/latest/objects/Fulfillment
- Shopify Developer Docs (third-party docs), FulfillmentStatus: https://shopify.dev/docs/api/admin-graphql/latest/enums/FulfillmentStatus
- Shopify Developer Docs (third-party docs), FulfillmentDisplayStatus: https://shopify.dev/docs/api/admin-graphql/latest/enums/FulfillmentDisplayStatus
- Shopify Developer Docs (third-party docs), FulfillmentTrackingInfo: https://shopify.dev/docs/api/admin-graphql/latest/objects/FulfillmentTrackingInfo
- Shopify Developer Docs (third-party docs), FulfillmentEvent: https://shopify.dev/docs/api/admin-graphql/latest/objects/FulfillmentEvent
- Shopify Developer Docs (third-party docs), FulfillmentEventStatus: https://shopify.dev/docs/api/admin-graphql/latest/enums/FulfillmentEventStatus
- Shopify Developer Docs (third-party docs), FulfillmentEventSortKeys: https://shopify.dev/docs/api/admin-graphql/latest/enums/FulfillmentEventSortKeys
- Shopify Developer Docs (third-party docs), Shopify API access scopes: https://shopify.dev/docs/api/usage/access-scopes
- Insonl: CRM Solutions · Generative AI · Free AI workflow audit · What an AI Assistant Should Pass to a Zendesk Agent · AI Customer Enquiry Automation in Vietnam
