How to Handle Refunds via Shopify GraphQL When REST Endpoint calculateRefund is Unavailable?

GraphQL Admin API Troubleshooting
1

Hi everyone,

We’re in the process of converting our Shopify integration from REST to GraphQL across all functionality. However, we’ve hit a blocker with the refunds flow.

Currently, we’re using the REST API endpoint calculateRefund to pre-screen refund data before actually submitting the refund. This helps catch issues like incorrect quantities or excessive refund amounts — the endpoint either returns errors or adjusts values accordingly.

Unfortunately, there doesn’t seem to be a GraphQL equivalent for this endpoint.

Questions:

  1. Has anyone found a workaround for refund pre-validation using GraphQL?
  2. Is there a best practice for submitting refund mutations directly and handling validation purely via the error messages returned?
  3. Are there risks or edge cases we should consider when skipping the pre-check done by calculateRefund?

We’d love to hear how others have solved this or if there’s an unofficial approach that’s working well in production.

Thanks in advance!

2

Hey Karl,

Thanks for describing the challenge your facing with migrating to GraphQL - I’ll be connecting with the internal team who owns this space to see what their recommendation is. In the meantime though, there is an example in our docs to calculate a refund by querying an order to get info that would be required to make this calculation:

query SuggestedRefund($id: ID!, $refundLineItems: [RefundLineItemInput!]) {
  order(id: $id) {
    id
    suggestedRefund(refundLineItems: $refundLineItems) {
      subtotalSet {
        shopMoney {
          amount
          currencyCode
        }
        presentmentMoney {
          amount
          currencyCode
        }
      }
      refundLineItems {
        lineItem {
          id
        }
        quantity
      }
    }
  }
}

With that info, you could perform the validation logic on your server. Would this approach not work for your use case?

Is there a best practice for submitting refund mutations directly and handling validation purely via the error messages returned?

So mutations like returnRefund do return detailed error messages in the userErrors field, which you can use to handle validation errors.

Are there risks or edge cases we should consider when skipping the pre-check done by calculateRefund?

Some things you’d need to look out for could be:

  • Incorrect Refund Amounts: Without pre-validation, you could refund more than the refundable amount or miss additional charges (e.g., fees or exchange items).
  • Concurrency Issues: If multiple refunds are processed simultaneously, the refundable quantities might change between fetching data and submitting the refund.
  • Complex Refund Scenarios: Shopify’s calculateRefund handles scenarios like partial refunds, adjustments, and fees, which you would need to replicate manually.

To mitigate these risks:

  • Fetch the latest order and line item details before submitting a refund.
  • Use Shopify’s userErrors to handle validation dynamically.
  • Implement server-side logic to validate refund amounts and quantities based on the fetched data.

You should also check out the Return.suggestedRefund and ReturnRefund documentation.

3

Thank you very much.