A buyer asks in chat: “Where is my refund for order #4108?” Two items went back under return #4108-R1: one is restocked with a pending gateway refund, while the second still requires processing and has no refund yet.
Shopify return status support automation breaks when a generative AI bot reads only Order.returnStatus, Order.displayFinancialStatus, or Refund.processedAt. Order-level badges collapse multiple returns and SKUs into one state, and a Refund record never proves funds cleared.
Using Shopify’s third-party docs (not an Insonl client), this guide separates item progress, parcel tracking, and payment settlement across GraphQL Admin. For outbound shipping and stock checks, see Shopify order-status replies and Shopify stock questions with live inventory.
A split return and a pending refund, side by side
This JSON is a made-up example payload (not from a real store or Insonl client), normalized from ReturnDetail and OrderReturnsOverview below to show one open return with split progress and a linked pending refund:
{
"return": {
"id":"gid://shopify/Return/501", "name":"#4108-R1", "status":"OPEN", "totalQuantity":2,
"returnLineItems":{"nodes":[
{"quantity":1, "processedQuantity":1, "unprocessedQuantity":0, "refundedQuantity":1,
"fulfillmentLineItem":{"lineItem":{"id":"gid://shopify/LineItem/901","title":"Trail Boot - 42","sku":"BOOT-42"}}},
{"quantity":1, "processedQuantity":0, "unprocessedQuantity":1, "refundedQuantity":0,
"fulfillmentLineItem":{"lineItem":{"id":"gid://shopify/LineItem/902","title":"Rain Shell - M","sku":"COAT-M"}}}
]},
"reverseFulfillmentOrders":{"nodes":[{"status":"OPEN", "lineItems":{"nodes":[
{"id":"gid://shopify/ReverseFulfillmentOrderLineItem/71", "totalQuantity":1,
"fulfillmentLineItem":{"lineItem":{"id":"gid://shopify/LineItem/901","sku":"BOOT-42"}},
"dispositions":[{"type":"RESTOCKED","quantity":1}]},
{"id":"gid://shopify/ReverseFulfillmentOrderLineItem/72", "totalQuantity":1,
"fulfillmentLineItem":{"lineItem":{"id":"gid://shopify/LineItem/902","sku":"COAT-M"}},
"dispositions":[{"type":"PROCESSING_REQUIRED","quantity":1}]}
]}}]}
},
"orderRefunds": [{
"id":"gid://shopify/Refund/812", "processedAt":"2026-11-20T14:12:00Z",
"return":{"id":"gid://shopify/Return/501"},
"refundLineItems":{"nodes":[{"quantity":1,"lineItem":{"id":"gid://shopify/LineItem/901"}}]},
"transactions":{"nodes":[{
"id":"gid://shopify/OrderTransaction/3301", "kind":"REFUND", "status":"PENDING",
"gateway":"shopify_payments", "formattedGateway":"Shopify Payments",
"amountSet":{"presentmentMoney":{"amount":"120.00","currencyCode":"USD"}}
}]}
}]
}
A naive bot reading Order.returnStatus (IN_PROGRESS) and Refund.processedAt replies: “Your 120.00 USD refund is complete.” Both halves are wrong: the transaction is PENDING, and COAT-M has no refund.
A grounded reply joins verified return items, reverse fulfillment order lines, and refund line items on LineItem.id (title/sku for display), links refunds via Refund.return.id, and separates both items:
- Trail Boot - 42 (
BOOT-42, qty 1): restocked; a 120.00 USD refund was initiated via Shopify Payments and is pending. - Rain Shell - M (
COAT-M, qty 1): markedPROCESSING_REQUIRED(requires further processing before being restocked or discarded); not yet processed or refunded.
Never invent an inspection stage or warehouse location absent from the enum. Per OrderTransaction, the live snapshot exposes transaction status, not a buyer-specific bank posting date; promise no clearing date because posting depends on the payment provider and issuer.
Fetch the order overview and return details separately
Shopify splits return state across four objects: Order (OrderReturnStatus, OrderDisplayFinancialStatus), Return (ReturnStatus, ReturnLineItemType, ReturnDecline, ExchangeLineItem), ReverseFulfillmentOrder (ReverseDelivery, ReverseFulfillmentOrderDispositionType), and Refund with OrderTransaction.
Nesting those connections under one order query can exceed Shopify’s 1,000-point single-query cost limit, because calculated cost multiplies nested first bounds before execution. Splitting into two bounded reads lowers requested cost, though exact cost must still be measured on your store: Order.refunds is an untruncated list ([Refund!]!), so if orders hold many refunds, fetch refund IDs first and page refundLineItems and transactions separately.
Step 1: authorize order access, then discover returns and order refunds. Authenticate the customer and verify authorization for that specific order before disclosing items, refunds, tracking, or label URLs. Omit first on Order.refunds so linked and unlinked refunds are never truncated. Starting from return(id:)? Resolve Return.order { id }, apply the same order-level check, and run this read:
query OrderReturnsOverview($orderId: ID!) {
order(id: $orderId) {
id name returnStatus displayFinancialStatus
returns(first: 10) {
pageInfo { hasNextPage endCursor }
nodes { id name status createdAt requestApprovedAt closedAt totalQuantity }
}
refunds {
id processedAt return { id }
refundLineItems(first: 10) {
pageInfo { hasNextPage endCursor }
nodes { quantity lineItem { id title sku } }
}
transactions(first: 10) {
pageInfo { hasNextPage endCursor }
nodes { id kind status errorCode processedAt gateway formattedGateway
amountSet { presentmentMoney { amount currencyCode } } }
}
}
}
}
Step 2: fetch one return’s items, exchanges, and reverse fulfillment orders. Run return(id:) per relevant return with pageInfo on every connection (if querying Return.refunds directly instead, paginate it and its nested connections too):
query ReturnDetail($returnId: ID!) {
return(id: $returnId) {
id name status createdAt requestApprovedAt closedAt totalQuantity
order { id }
decline { reason note }
returnShippingFees { id amountSet { presentmentMoney { amount currencyCode } } }
returnLineItems(first: 10) {
pageInfo { hasNextPage endCursor }
nodes {
id quantity processableQuantity processedQuantity
unprocessedQuantity refundableQuantity refundedQuantity
returnReasonDefinition { handle name }
... on ReturnLineItem {
restockingFee { percentage amountSet { presentmentMoney { amount currencyCode } } }
fulfillmentLineItem { lineItem { id title sku } }
}
... on UnverifiedReturnLineItem { unitPrice { amount currencyCode } }
}
}
exchangeLineItems(first: 10) {
pageInfo { hasNextPage endCursor }
nodes { id title variantSku quantity processedQuantity unprocessedQuantity }
}
reverseFulfillmentOrders(first: 3) {
pageInfo { hasNextPage endCursor }
nodes {
id status thirdPartyConfirmation { status }
lineItems(first: 10) {
pageInfo { hasNextPage endCursor }
nodes { id totalQuantity fulfillmentLineItem { lineItem { id title sku } }
dispositions { type quantity createdAt } }
}
reverseDeliveries(first: 3) {
pageInfo { hasNextPage endCursor }
nodes {
id
reverseDeliveryLineItems(first: 5) {
pageInfo { hasNextPage endCursor }
nodes { quantity reverseFulfillmentOrderLineItem { id } }
}
deliverable { ... on ReverseDeliveryShippingDeliverable {
label { publicFileUrl } tracking { carrierName number url }
}}
}
}
}
}
}
}
Follow cursor-based pagination whenever hasNextPage is true, passing endCursor as after on that parent’s connection. If any branch stays incomplete or GraphQL returns errors with partial data, qualify the reply or escalate.
Keep four schema rules straight:
- Non-linear states:
ReturnStatus(REQUESTED,OPEN,DECLINED,CANCELED,CLOSED) lists possible states, not a fixed linear sequence. - Fee ownership:
returnShippingFeessits onReturn;restockingFeesits only on verified ReturnLineItem, notReturnor UnverifiedReturnLineItem. - Interface fragments:
Return.returnLineItemsreturnsReturnLineItemType. Omitting... on ReturnLineItemdropsfulfillmentLineItemandrestockingFee; omitting... on UnverifiedReturnLineItemdropsunitPrice, while unverified nodes still return interface fields. - Transaction amounts:
Refund.totalRefundedSetaggregates transactions. ReadamountSet.presentmentMoneyandgatewayon eachkind: REFUNDtransaction so split refunds (such as card plus store credit) are reported separately, and state amounts at refund level when payment cannot be allocated unambiguously to one item.
What support can safely tell the buyer about items, parcels, and payments
Evaluate the assembled snapshot in deterministic code before an LLM writes prose:
| Live Shopify state | What the assistant states | Guard or escalation |
|---|---|---|
Return.status == REQUESTED |
Request is logged for listed items and awaiting review. | Never promise approval or a label. |
Return.status == DECLINED |
State decline.reason (FINAL_SALE, RETURN_PERIOD_ENDED, OTHER) and decline.note. |
Escalate if buyer disputes policy. |
Return.status == OPEN, no dispositions |
Approved. Join parcels via reverseDeliveryLineItems.reverseFulfillmentOrderLineItem.id (ReverseDeliveryLineItem) for each parcel’s label URL and tracking, or note none is attached. |
ReverseDeliveryTrackingV2 exposes only carrierName, number, and url—never claim receipt from Shopify alone. |
Return.status == OPEN, partial progress (within one line: processedQuantity > 0 and unprocessedQuantity > 0, or across lines) |
Report per-line processedQuantity, unprocessedQuantity, refundedQuantity, dispositions, and any restockingFee, alongside return-level returnShippingFees once per return. |
Escalate on MISSING, NOT_RESTOCKED, or overdue PROCESSING_REQUIRED. |
REFUND transaction status == SUCCESS |
Report each transaction’s amountSet.presentmentMoney and method (shopify_store_credit as store credit; formattedGateway if present; unspecified if absent). State Shopify recorded transaction success. |
Bank receipt remains unconfirmed; promise no posting date. |
REFUND transaction status in PENDING or AWAITING_RESPONSE |
Report each transaction’s amount and method separately as initiated and pending. | Never say funds cleared. |
REFUND transaction status in FAILURE, ERROR, or UNKNOWN |
Do not tell the buyer the refund succeeded. | Escalate with return name, refund ID, status, and errorCode. |
Return.status == CLOSED, relevant lines have refundedQuantity == 0 |
Report exchangeLineItems (processedQuantity, unprocessedQuantity), or check candidate unlinked Order.refunds via refundLineItems.lineItem.id and quantity. |
Escalate if unlinked match is ambiguous, absent, or neither exists. |
Return.status == CANCELED |
Return canceled, restoring affected items to fulfilled status per returnCancel. | Escalate if buyer already shipped the parcel. |
On escalation, write return ID, line counts, dispositions, transaction statuses, and errorCode into structured helpdesk fields—see Zendesk AI handoff ticket fields.
Operational traps: closure, unlinked refunds, scopes, and webhooks
- Closure without payment and unlinked refunds. Per Apps in returns, Build for return management, and returnClose, returnProcess links a refund when issuing one and closes the return once all items are processed and disposed;
removeFromReturncloses it when all items are removed;returnClosecan close the return manually, even with zero refunded units. Manual refundCreate without a return link lands only inOrder.refunds(Refund.return: null). MatchingrefundLineItems.lineItem.idandquantityfinds only a candidate match (identical line/quantity pairs can repeat across returns or refunds): escalate ambiguous matches, inspectOrderTransaction.gateway(shopify_store_creditidentifies store credit inrefundCreateexamples; leave method unspecified if absent), and report amounts at refund level when item allocation is ambiguous. - Immutable dispositions and 3PL confirmation. Per Manage reverse fulfillment orders, dispositions apply per unit and cannot be updated via API after creation, so
MISSINGorNOT_RESTOCKEDdisputes need human review. For 3PL returns, checkthirdPartyConfirmation.status(ReverseFulfillmentOrderThirdPartyConfirmationStatus:PENDING_ACCEPTANCE,ACCEPTED,REJECTED,PENDING_CANCELATION,CANCEL_ACCEPTED,CANCEL_REJECTED) to flag rejected handoffs. - Scopes, 60-day window, and protected data. Per Shopify API access scopes and object docs, these reads need
read_ordersandread_returns(ExchangeLineItemandReturnReasonDefinitiondocumentread_returns;Orderalso listsread_quick_sale, which omits nested refund/fulfillment-line objects). Addinglocation { name }on dispositions requiresread_locations,read_inventory, orread_markets_home.read_orderscovers 60 days; pair it withread_all_ordersfor older orders (Partner apps need Shopify approval; qualifying merchant-org Dev Dashboard apps for own-org stores do not). Apps reading order/customer fields must also meet protected customer data rules where applicable. - Admin webhooks and transaction updates. The Customer Account API also exposes
Return, while admin return management and return webhooks live in GraphQL Admin. Per WebhookSubscriptionTopic, subscribe toreturns/request,returns/approve,returns/decline,returns/process,returns/close,returns/cancel,returns/reopen,returns/update,reverse_fulfillment_orders/dispose,reverse_deliveries/attach_deliverable,refunds/create, andorder_transactions/create. Becauserefunds/createfires independently of money movement andorder_transactions/createfires on creation or updates tosuccess,failure, orerror, re-read pending or ambiguous transactions live before replying.
Before wiring return data into a support bot
Insonl is a Ho Chi Minh City engineering studio building CRM integrations and generative AI workflows. Before connecting an assistant to live returns and refunds, map your partial-return rules, unlinked-refund checks, and escalations with our free AI workflow audit.
The audit is free; work after it is charged separately.
Sources
- Shopify Developer Docs (third-party): order query, Order, OrderReturnStatus, OrderDisplayFinancialStatus, Return, ReturnStatus, ReturnLineItemType, ReturnLineItem, UnverifiedReturnLineItem, ReturnDecline, ExchangeLineItem, ReverseFulfillmentOrder, ReverseFulfillmentOrderDispositionType, ReverseFulfillmentOrderThirdPartyConfirmationStatus, ReverseDelivery, ReverseDeliveryLineItem, ReverseDeliveryTrackingV2, Refund, RefundLineItem, OrderTransaction, OrderTransactionStatus, WebhookSubscriptionTopic, returnProcess, returnClose, returnCancel, refundCreate, Apps in returns, Build for return management, Manage reverse fulfillment orders, GraphQL rate limits, GraphQL pagination, API access scopes, Protected customer data, Customer Account API Return
- Insonl: CRM Solutions, Generative AI, Free AI workflow audit, Shopify Order-Status Replies, Shopify Stock Questions With Live Inventory, Zendesk AI Handoff Ticket Fields
