---
title: Migrating to returns processing - interim solution
description: This guide explains upcoming changes to Shopify's return processing system and provides migration instructions for partners using the GraphQL Admin API.
source_url:
  html: https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/migrate-to-return-processing-interim-solution
  md: https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/migrate-to-return-processing-interim-solution.md
---

# 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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnRefund) mutation.

***

## Impact

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.

***

## Interim solution

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

### How 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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnCreate) and [`returnApproveRequest`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnApproveRequest) mutations that controls when return sales are recorded.

### How 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

```graphql
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

```graphql
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](https://cdn.shopify.com/shopifycloud/shopify-dev/production/assets/assets/images/apps/fulfillments/return-apps/Interim-solution-lifecycle-_IBKV1Rs.png)

### Eligibility

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

#### Example

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

***

## Migration timeline

| Date | Milestone | Details |
| - | - | - |
| May 5, 2025 | Rollout starts | Interim 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, 2025 | `returnProcess` mutation on stable | Default 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, 2026 | Interim solution deprecated | The 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. |

***

## Important 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

***