---
title: Deprecation of legacy return APIs and improvements to return management - Shopify developer changelog
description: Shopify’s developer changelog documents all changes to Shopify’s platform. Find the latest news and learn about new platform opportunities.
source_url:
  html: https://shopify.dev/changelog/deprecation-of-legacy-return-apis-and-improvements-to-return-management
  md: https://shopify.dev/changelog/deprecation-of-legacy-return-apis-and-improvements-to-return-management.md
---

[Back to Developer changelog](https://shopify.dev/changelog)

May 21, 2025

Tags:

* Action Required
* Admin GraphQL API
* 2025-07

# 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`](https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/returnRefund) mutation is deprecated and replaced by the new [`returnProcess`](https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/returnProcess) mutation. The [`returnProcess`](https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/returnProcess) mutation streamlines return lifecycle management by combining disposition decisions and financial processing into a single call.
* The field [`Return.suggestedReturnRefund`](https://shopify.dev/docs/api/admin-graphql/2025-07/objects/suggestedReturnRefund) is deprecated in favor of the new [`Return.suggestedFinancialOutcome`](https://shopify.dev/docs/api/admin-graphql/2025-07/objects/SuggestedReturnFinancialOutcome) 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`](https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/returnCreate) or approves return requests using [`returnApproveRequest`](https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/returnApproveRequest), migrate to the new [`returnProcess`](https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/returnProcess) mutation to handle refunds and exchanges. The older mutations ([`refundCreate`](https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/refundCreate), [`returnRefund`](https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/returnRefund)) and the query field ([`Return.suggestedRefund`](https://shopify.dev/docs/api/admin-graphql/2025-07/objects/suggestedRefund)) are deprecated. Instead, you should now use [`returnProcess`](https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/returnProcess) and [`Return.suggestedFinancialOutcome`](https://shopify.dev/docs/api/admin-graphql/2025-07/objects/SuggestedReturnFinancialOutcome).

**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](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/migrate-to-return-processing).