---
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
metadata:
  effectiveApiVersion: 2025-07
  affectedApi:
    - displayName: Admin GraphQL API
      handle: admin-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: Breaking API Change
    handle: breaking-api-change
  indicatesActionRequired: true
  createdAt: '2025-04-15T12:37:16-04:00'
  postedAt: '2025-05-21T13:00:00-04:00'
  updatedAt: '2025-05-21T12:30:41-04:00'
  effectiveAt: '2025-10-01T12:00:00-04:00'
---

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).