---
title: >-
  Returns Processing APIs replaces Return Refund APIs - 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/posts/returns-processing-api'
  md: 'https://shopify.dev/changelog/posts/returns-processing-api.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: false
  createdAt: '2025-01-29T13:23:33-05:00'
  postedAt: '2025-07-01T01:00:00-04:00'
  updatedAt: '2025-06-20T16:04:42-04:00'
  effectiveAt: '2025-04-01T12:00:00-04:00'
---

July 1, 2025

# Returns Processing APIs replaces Return Refund APIs

DateJuly 1, 2025

Version[2025-07](https://shopify.dev/changelog?api_version=2025-07)

Flags[Breaking API Change](https://shopify.dev/changelog?filter=breaking-api-change)

SurfacesAPI

Affected APIs[Admin GraphQL API](https://shopify.dev/changelog?api_type=admin-graphql)

As [announced previously](https://shopify.dev/changelog/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.
* 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`](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 officially launched 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).