Return and Refund Rest Api

Products and Orders APIs
1

Hello,

I have implemented the order return and refund process with SAP. However, I am facing an issue with the refund REST API.

Refund API URL:
/admin/api/2025-01/orders/450789469/refunds.json
Refund request body (Sample JSON):
{
“refund”: {
“currency”: “USD”,
“notify”: true,
“note”: “wrong size”,
“shipping”: {
“full_refund”: true
},
“refund_line_items”: [
{
“line_item_id”: 518995019,
“quantity”: 1,
“restock_type”: “return”,
“location_id”: 487838322
}
],
“transactions”: [
{
“parent_id”: 801038806,
“amount”: 41.94,
“kind”: “refund”,
“gateway”: “bogus”
}
]
}
}
The refund is successfully processed, and the quantity is returned to the inventory. However, the order status is not set to Return Closed, and the item is not restocked properly. Additionally, the Restock button is still visible in the admin order details page.
Could you please help me identify what I am missing?

1 Like
2

Hey @Soroj_Jana

Looking at your issue with the refund REST API, I can clarify what’s happening. The REST API endpoint you’re using handles the refund process correctly, which is why you’re seeing the quantity returned to inventory. However, this endpoint doesn’t manage the return workflow status.

For managing the complete return process (including marking returns as closed and handling the return status), you’ll need to use the GraphQL Admin API instead as this isn’t available in our REST api’s.

This limitation explains why your order status isn’t changing to “Return Closed” and why the Restock button is still visible in the admin.

To implement refund management, we have a comprehensive guide here:

1 Like
3

Hey Kyle,

Is there a specific graphQL query to the return data of an order like this?

sorry to hijack, but i would love an query that gets the return/exchange dataset of an order.

4

Could you use the returns field on the order query? See: Order - GraphQL Admin

5

Hey @Liam-Shopify

Thanks for sharing.

I have looked at this actually, what I would really like to do is not query orders (ie: gid://shopify/Order/XXXX) but actually query returns (ie: gid://shopify/Return/XXXX) and get the following (or really all that is currently related to a return.

  • refunds
  • returnsLineItems
  • reverseFulfillmentOrders
  • exchangeLineItems
  • all the other connections related to it

I would really like a query (likes orders), that can get returns by status, date etc, so like:

query Return {
    return(id: "gid://shopify/Return/XXXX") {
}

or

query Returns {
    returns(first: 30) {
}
6

If you have the return ID, you can query it directly with a return query

query {
  return(id: "gid://shopify/Return/945000954") {
    status
    name
    order {
      id
    }
    returnLineItems(first: 10) {
      edges {
        node {
          ... on ReturnLineItem {
            fulfillmentLineItem {
              lineItem {
                name
              }
            }
            totalWeight {
              value
            }
          }
          quantity
          returnReason
          returnReasonNote
        }
      }
    }
  }
}

Alternatively, for multiple returns, there isn’t an returns endpoint, but you can query orders and filter by only orders with returns: Orders query filter on return status