Deprecation of legacy return APIs and improvements to return management

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.

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 are available now in the unstable API version and officially launch in API version 2025-07.

For more details, see our updated migration guide.