Developer changelog

As of 2024-07 in the GraphQL Admin API, Shopify’s suggestion for refund is inclusive of payable charges, such as exchange items and fees, alongside returns.

The Return.suggestedRefund query and ReturnRefund mutation APIs will now have a different expectation on the refund amount. The refund amount considers exchange line items and fees on the return, as well as any outstanding amount owed by the buyer on an order.

This affects the logic for 2024-07 versions and onwards, the logic for previous API versions will continue to only account for return line items.

Here is an example for an order with a return for an item worth $50.99 CAD and a return fee of $5 CAD, given this suggested return refund query:

query {
  return(id: "exampleReturn/1") {
    suggestedRefund(
      returnRefundLineItem: [
        {
          returnLineItemId: "exampleReturnLineItem/1"
          quantity: 1
        }
      ]
    ) {
      amount {
        shopMoney {
          amount
          currencyCode
        }
      }
    }
  }
}

Result with previous behavior

{
  "data": {
    "return": {
      "suggestedRefund": {
        "amount": {
          "shopMoney": {
            "amount": "50.99",
            "currencyCode": "CAD"
          }
        }
      }  
    }
  }
}

Result with new behavior:

{
  "data": {
    "return": {
      "suggestedRefund": {
        "amount": {
          "shopMoney": {
            "amount": "45.99",
            "currencyCode": "CAD"
          }
        }
      }  
    }
  }
}

Note that if the return fee was greater than $50.99 CAD, the suggested amount cannot be lower than $0 CAD.