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

ExpandOn this page

* [Impact](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/migrate-to-return-processing-interim-solution#impact)
* [Interim solution](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/migrate-to-return-processing-interim-solution#interim-solution)
* [Migration timeline](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/migrate-to-return-processing-interim-solution#migration-timeline)
* [Important considerations](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/migrate-to-return-processing-interim-solution#important-considerations)

# 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 will preserve the current behavior of recording return sales at return creation for all returns created via API until July 1. This will be the default, but partners will be able to opt into the new behavior early.

The default will change to the new behavior on July 1 **for all API versions**. From July 1 until January 1, 2026, the interim solution will remain available, but only for shops that created exchanges or returns with return fees prior to July 1 (those shops will be 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 will always behave as if it were `true`.

* **After January 1, 2026**: The `unprocessed` parameter will be set to `true` for all merchants and cannot 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 January 1, 2026:** The interim solution will only function for merchants who have created exchanges or returns with fees using API prior to July 1, 2025. For all other merchants, the parameter will have no effect, and they will 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 will be eligible for the interim solution after July 1. Your app will need 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`, will 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 will always behave as if it were `true`. Partners can integrate with the new `returnProcess` mutation on a stable API version. |
| January 1, 2026 | Interim solution deprecated | The interim solution is fully deprecated. The `unprocessed` parameter will be set to `true` for all merchants and cannot be overridden. All returns will 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 may 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 January 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 January 1, 2026: All merchants must use the `returnProcess` mutation

***

* [Impact](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/migrate-to-return-processing-interim-solution#impact)
* [Interim solution](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/migrate-to-return-processing-interim-solution#interim-solution)
* [Migration timeline](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/migrate-to-return-processing-interim-solution#migration-timeline)
* [Important considerations](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/migrate-to-return-processing-interim-solution#important-considerations)