Returns Processing APIs replaces Return Refund APIs

As announced previously, we're introducing important changes to simplify and enhance return management in the Shopify Admin API.

What's changing?

• The returnRefund mutation is deprecated and replaced by the new returnProcess mutation. The returnProcess mutation streamlines return lifecycle management by combining disposition decisions and financial processing into a single call.
• The field Return.suggestedReturnRefund is deprecated in favor of the new Return.suggestedFinancialOutcome field.
• Exchange fulfillment orders are now created only when exchange line items are processed, ensuring accuracy.
• Refunds and return processing now offer enhanced precision for managing returned line items.
• Only exchanges with a net payable balance due by the buyer are placed on hold with AWAITING_PAYMENT hold reason.

Action required:
If your app currently creates returns using returnCreate or approves return requests using returnApproveRequest, migrate to the new returnProcess mutation to handle refunds and exchanges. The older mutations (refundCreate, returnRefund) and the query field (Return.suggestedRefund) are deprecated. Instead, you should now use returnProcess and Return.suggestedFinancialOutcome.

Availability:
These new APIs officially launched in API version 2025-07.

For more details, see our updated migration guide.