API migration guide

Shopify Returns API migration guide: returnProcess, returnRefund, and 2025-07

Reviewed August 31, 2026 Evidence confidence: Official Shopify developer changelog and docs Primary domain: Returns / refunds / exchanges

Current decision Treat this as a migration project, not a simple rename. Apps that create returns, approve return requests, process refunds, manage exchanges, or calculate return financial outcomes should move return completion to returnProcess, read Return.suggestedFinancialOutcome, and test refunds, exchange items, duties, shipping, and user errors together.

What changed?

Shopify's Admin GraphQL API 2025-07 officially launched return processing APIs. The key migration is from older return-refund handling to a return-processing flow:

Old surface	New surface	Why it matters
`returnRefund`	`returnProcess`	Return disposition, exchange item handling, and optional financial processing move into one return-processing step.
`Return.suggestedReturnRefund`	`Return.suggestedFinancialOutcome`	Apps should calculate the recommended financial result from the newer return financial outcome model.
`Return.suggestedRefund`	`Return.suggestedFinancialOutcome`	Older suggested-refund reads are deprecated in the migration path described by Shopify.
Refund-only return flow	Return processing flow	Returns can involve restocking, disposal, exchange line items, shipping refunds, duty refunds, and financial transfers.

Who is affected?

This affects Shopify apps and integrations that use the Admin GraphQL API for return management, especially apps that:

Create returns with returnCreate.
Approve return requests with returnApproveRequest.
Issue return refunds through returnRefund or older refund logic.
Read Return.suggestedReturnRefund or Return.suggestedRefund.
Coordinate exchanges, restocking, disposal, refund shipping, refund duties, or return-line-item financial transfers.
Maintain support, returns, ERP, 3PL, accounting, or customer-service tooling around Shopify return data.

What can break?

Deprecated mutation risk: apps that keep building around returnRefund are building on a deprecated return-refund path.
Financial outcome mismatch: refund and exchange logic can drift if the app still reads old suggested-refund fields instead of suggestedFinancialOutcome.
Exchange handling errors: Shopify says exchange fulfillment orders are created when exchange line items are processed, so exchange behavior must be tested through the return-processing flow.
Partial-return complexity: refunds, duties, shipping refunds, item disposition, and exchange items need to be tested together, not as isolated refund calls.
Permission surprises: the return-processing mutation requires return-writing access scopes, and refunding may require the user permission to refund orders.

Migration map

Find in code	What to check	Safer replacement path
`returnRefund`	Where the app issues refund money for an existing return	Move completion to `returnProcess(input: ReturnProcessInput!)`
`refundCreate`	Whether it is used as part of a return-management flow	Use return processing for return-driven refunds and keep standalone refunds separate only when appropriate
`suggestedReturnRefund`	Where the app calculates or previews return refund amounts	Read `Return.suggestedFinancialOutcome`
`suggestedRefund`	Any older suggested-refund query fields	Replace with the newer suggested financial outcome model
`returnCreate` / `returnApproveRequest`	Whether the app creates or approves a return but finishes financial processing elsewhere	Keep creation/approval logic where needed, then process the return through `returnProcess`

Codebase search checklist

Start by searching for these exact strings across the app, background workers, webhook handlers, and internal admin tools:

returnRefund
refundCreate
returnCreate
returnApproveRequest
suggestedReturnRefund
suggestedRefund
suggestedFinancialOutcome
returnLineItems
exchangeLineItems
refundShipping
refundDuties

Do not only search the main app. Returns logic often appears in support tooling, ERP syncs, customer-service dashboards, fulfillment workflows, warehouse scripts, scheduled jobs, and webhook consumers.

Return-processing flow to test

Create or approve the return. Keep existing returnCreate or approval flow only where it still matches Shopify's current return lifecycle.
Query the return state. Fetch the return ID, return line items, exchange line items, current status, and suggestedFinancialOutcome.
Build the process input. Prepare ReturnProcessInput with the returned item quantities, exchange line item quantities, disposition decisions, notification choice, and any financial transfer details.
Call returnProcess. Handle userErrors as first-class migration failures, not just logs.
Verify downstream results. Check the processed return, created exchange fulfillment orders, refund transaction records, merchant financial reports, customer notifications, and any app-side sync jobs.

Minimal mutation shape

This is not a complete production payload. It is the shape your migration should be organized around:

mutation ProcessReturn($input: ReturnProcessInput!) {
  returnProcess(input: $input) {
    return {
      id
      status
    }
    userErrors {
      field
      message
      code
    }
  }
}

Test cases before production

Case	Why to test it	What to verify
Full refund, no exchange	Baseline return financial processing	Refund amount, customer notification, return status, financial report record
Partial refund	Line-item quantities and financial outcome can diverge	Correct quantities, item totals, taxes, and refund transaction amount
Exchange item	Exchange fulfillment orders are tied to return processing	Exchange fulfillment order created only when expected
Refund shipping	Shipping may be optional or policy-dependent	Shipping refund amount and customer-facing refund total
Refund duties	Cross-border returns can have duty handling	Duty refund behavior and financial report result
Restock vs dispose	Disposition affects inventory and operations	Inventory, restock behavior, warehouse instructions, and app sync
User error path	Migration bugs often surface as structured API errors	App displays or logs `userErrors.field`, `message`, and `code`

Smallest safe migration

Inventory all return/refund surfaces. Search code, jobs, webhook consumers, support dashboards, and internal tools.
Separate return-driven refunds from standalone refunds. Do not blindly replace every refund call if it is not part of a return workflow.
Replace deprecated return-refund reads. Move return financial previews to Return.suggestedFinancialOutcome.
Move return completion to returnProcess. Include item quantities, exchange line items, dispositions, and optional financial transfer details.
Update permissions and error handling. Confirm access scopes and refund permissions, and treat userErrors as a required migration surface.
Run the full matrix above in staging. Test refund, exchange, shipping, duties, restock/dispose, partial returns, and failed/error states.
Ship behind a controlled release. Monitor return processing, support tickets, financial reports, webhook jobs, and fulfillment-order creation after release.

Do not over-migrate blindly. This page is specifically about Shopify return-processing flows. A refund that is not tied to a return lifecycle may need separate treatment. Confirm the business meaning of each call before replacing it.

Search phrases this page answers

Shopify returns API, Shopify returnProcess API, Shopify returnRefund deprecated, Shopify returnProcess mutation, Shopify ReturnProcessInput, Shopify suggestedFinancialOutcome, Shopify suggestedReturnRefund deprecated, Shopify return API migration, Shopify 2025-07 returns API, Shopify exchange fulfillment orders, Shopify refund shipping duties, and Shopify Admin GraphQL returns processing.

Official sources

Independent research, not official Shopify support. Test all return, refund, exchange, permission, and financial-outcome flows before changing production app behavior.