Skip to main content

Migrating to returns processing - interim solution

Shopify is changing how return sales are recorded in our system. Currently, return sales (including exchange items and return fees) are recorded at the time of return creation. With our upcoming improvements, return sales will be recorded at the time of return processing instead.

This change affects Partners who manage the following processes:

  • Create exchanges using Shopify's exchange types.
  • Create returns with fees without calling the returnRefund mutation.

Anchor to ImpactImpact

If you don't migrate your app, merchants might be impacted in the following ways:

  • Exchange items on the return won't be converted into line items on the order.
  • Fulfillment orders might be missing for the exchange items.
  • Incorrect financial reporting for return items, fees, and exchange items might result.

Anchor to Interim solutionInterim solution

To ensure a smooth transition, Shopify is implementing a temporary solution for affected merchants.

Anchor to How it worksHow it works

The interim solution preserves the current behavior of recording return sales at return creation for all returns created via API until July 1. This is the default, but partners can opt into the new behavior early.

The default changes to the new behavior on July 1 for all API versions. From July 1 until March 1, 2026, the interim solution remains available, but only for shops that created exchanges or returns with return fees prior to July 1. These shops are added to an allowlist that triggers legacy behavior.

The interim solution uses an undocumented API parameter, unprocessed, on the returnCreate and returnApproveRequest mutations that controls when return sales are recorded.

Anchor to How the ,[object Object], parameter worksHow the unprocessed parameter works

  • Before July 1, 2025: By default, the unprocessed parameter is set to false, meaning returns are processed immediately and sales are recorded at the time of return creation (current behavior). Partners can set unprocessed: true to opt into the new behavior early.

  • After July 1, 2025: By default, the unprocessed parameter is set to true for all merchants except those on the allowlist. For merchants on the allowlist (those who created exchanges or returns with fees before July 1), the default remains false (legacy behavior), but partners can override this by setting unprocessed: true. For non-allowlisted merchants, the parameter always behaves as if it were true.

  • After March 1, 2026: The unprocessed parameter is set to true for all merchants and can't be overridden.

    Example: Creating a Return

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

returnCreate GraphQL mutation

mutation returnCreateMutation {
returnCreate(
returnInput: {
# When `true` the return will be created in an unprocessed state
# Returns must subsequently be processed via Return Processing APIs in order to take further action on them.
# Creating returns in an unprocessed state will soon be the default behavior.
# Defaults to `false`
unprocessed: true,
# ...other return input fields
}
)
{
return {
id
}
userErrors {
field
message
}
}
}

Example: Approving a Requested Return

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

returnApproveRequest GraphQL mutation

mutation ApproveReturnRequestMutation {
returnApproveRequest(
input: {
# When `true` the return will be created in an unprocessed state
# Returns must subsequently be processed via Return Processing APIs in order to take further action on them.
# Creating returns in an unprocessed state will soon be the default behavior.
# Defaults to `false`
unprocessed: true,
# ...other return input fields
}
) {
return {
id
status
}
userErrors {
field
message
}
}
}
Note

When the interim solution is enabled for a shop it applies to all returns created using the API (not just returns with return fees or exchanges), but not for returns created through the Shopify admin interface.

The following diagram shows the lifecycle of the interim solution:

A diagram showing the lifecycle of the interim solution

Anchor to EligibilityEligibility

  • May 5, 2025 to July 1, 2025: The interim solution is available for all shops creating returns via API

  • July 1, 2025 to March 1, 2026: The interim solution only functions for merchants who have created exchanges or returns with fees using API prior to July 1, 2025. For all other merchants, the parameter has no effect, and they automatically use the new behavior.

    As of July 1, 2025, Partners should use the new returnProcess mutation to handle returns with fees or exchanges for merchants wanting these options.

Anchor to ExampleExample

  • Merchant A uses your app to create returns with exchange items.

  • Merchant B starts using your app on July 2 and wants to create returns with exchange items or return fees.

  • Merchant C uses your app to create returns without exchange items or return fees.

    Only merchant A is eligible for the interim solution after July 1. Your app needs to migrate to the new mutation to support merchant B.

    For Merchant C, we recommend issuing refunds using the dedicated return refund mutations, such as returnProcess (previously returnRefund), to ensure that the correct item is refunded. However, other refund mutations, like refundCreate, still work for this simple use case.

Anchor to Migration timelineMigration timeline

DateMilestoneDetails
May 5, 2025Rollout startsInterim solution is activated for all shops creating returns via public Admin APIs. By default, returns are processed immediately and sales recorded at creation time (unprocessed: false). Partners can set unprocessed: true to opt into the new behavior early.
July 1, 2025returnProcess mutation on stableDefault behavior changes to creating unprocessed returns (unprocessed: true) for all merchants except those on the allowlist. For allowlisted merchants (those who created exchanges or returns with fees before July 1), the default remains false, but partners can set unprocessed: true to opt into the new behavior. For non-allowlisted merchants, the parameter always behaves as if it were true. Partners can integrate with the new returnProcess mutation on a stable API version.
March 1, 2026Interim solution deprecatedThe interim solution is fully deprecated. The unprocessed parameter is set to true for all merchants and can't be overridden. All returns use the new behavior of recording sales at processing time. Partners must use the returnProcess mutation for all merchants requiring exchanges or return fees.

Anchor to Important considerationsImportant considerations

  • Shopify admin versus API inconsistency: The interim solution applies only to returns created using the GraphQL Admin API, not through the Shopify admin interface which always uses the new solution. This might cause inconsistencies in reporting that merchants might notice.
  • Default behavior changes: Be aware of how the unprocessed parameter default changes over time:
    • Before July 1, 2025: Default is false for all merchants (legacy behavior)
    • After July 1, 2025: Default is true for non-allowlisted merchants, remains false for allowlisted merchants
    • After March 1, 2026: Permanently set to true for all merchants
  • Integrating with Exchanges: After July 1, 2025, exchanges created with existing mutations only operate by default for merchants on the allowlist. For these merchants, partners can opt into the new behavior by setting unprocessed: true. All other merchants require the use of the returnProcess mutation to successfully create and process exchanges.
  • Return fees: Partners creating returns with fees must adapt based on the merchant and time period:
    • Before July 1, 2025: All merchants can use existing mutations (with default unprocessed: false) or opt into unprocessed: true early
    • After July 1, 2025: Allowlisted merchants can continue using existing mutations (default behavior), while non-allowlisted merchants must use the returnProcess mutation
    • After March 1, 2026: All merchants must use the returnProcess mutation
Was this page helpful?