What Just ChangedAPI changes
API change record

Shopify returnProcess replaces legacy return refund APIs

Reviewed August 10, 2026Evidence confidence: Official Shopify developer changelogPrimary domain: Returns / refunds / exchanges
Current decisionApps that create returns, approve return requests, or coordinate refunds and exchanges should migrate to returnProcess and Return.suggestedFinancialOutcome instead of continuing to build on deprecated return-refund APIs.

What changed?

Shopify introduced return-management changes in Admin GraphQL API version 2025-07. The returnRefund mutation is deprecated and replaced by returnProcess, and Return.suggestedReturnRefund is deprecated in favor of Return.suggestedFinancialOutcome.

Who is affected?

This affects apps that create returns with returnCreate, approve return requests with returnApproveRequest, or handle refunds and exchanges using older return/refund mutations and fields.

What can break?

  • Return, refund, and exchange flows can drift from Shopify's current return lifecycle model.
  • Apps may keep relying on deprecated fields while the platform expects return processing and financial outcomes together.
  • Fulfillment and exchange behavior can be inaccurate if exchange line items are not processed through the new flow.

Smallest safe migration

  1. Inventory every return, refund, and exchange mutation your app calls.
  2. Replace return/refund handling with returnProcess where applicable.
  3. Replace suggested refund fields with Return.suggestedFinancialOutcome.
  4. Test return lifecycle paths: requested, approved, refunded, exchanged, partially refunded, and failed.

Official sources

Independent research, not official Shopify support. Test all return and refund flows before changing production app behavior.