insonl
← journal

How to Answer Shopify Return-Status Questions From Live Data

date
21 November 2026
by
Insonl
read
7 min read

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): marked PROCESSING_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: returnShippingFees sits on Return; restockingFee sits only on verified ReturnLineItem, not Return or UnverifiedReturnLineItem.
  • Interface fragments: Return.returnLineItems returns ReturnLineItemType. Omitting ... on ReturnLineItem drops fulfillmentLineItem and restockingFee; omitting ... on UnverifiedReturnLineItem drops unitPrice, while unverified nodes still return interface fields.
  • Transaction amounts: Refund.totalRefundedSet aggregates transactions. Read amountSet.presentmentMoney and gateway on each kind: REFUND transaction 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

  1. 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; removeFromReturn closes it when all items are removed; returnClose can close the return manually, even with zero refunded units. Manual refundCreate without a return link lands only in Order.refunds (Refund.return: null). Matching refundLineItems.lineItem.id and quantity finds only a candidate match (identical line/quantity pairs can repeat across returns or refunds): escalate ambiguous matches, inspect OrderTransaction.gateway (shopify_store_credit identifies store credit in refundCreate examples; leave method unspecified if absent), and report amounts at refund level when item allocation is ambiguous.
  2. Immutable dispositions and 3PL confirmation. Per Manage reverse fulfillment orders, dispositions apply per unit and cannot be updated via API after creation, so MISSING or NOT_RESTOCKED disputes need human review. For 3PL returns, check thirdPartyConfirmation.status (ReverseFulfillmentOrderThirdPartyConfirmationStatus: PENDING_ACCEPTANCE, ACCEPTED, REJECTED, PENDING_CANCELATION, CANCEL_ACCEPTED, CANCEL_REJECTED) to flag rejected handoffs.
  3. Scopes, 60-day window, and protected data. Per Shopify API access scopes and object docs, these reads need read_orders and read_returns (ExchangeLineItem and ReturnReasonDefinition document read_returns; Order also lists read_quick_sale, which omits nested refund/fulfillment-line objects). Adding location { name } on dispositions requires read_locations, read_inventory, or read_markets_home. read_orders covers 60 days; pair it with read_all_orders for 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.
  4. 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 to returns/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, and order_transactions/create. Because refunds/create fires independently of money movement and order_transactions/create fires on creation or updates to success, failure, or error, 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