# Exchanges V2 Deprecation and Migration

Shopify is deprecating the ExchangesV2 API, and has migrated the Retail exchange implementation over to using the platform’s exchange implementation.

## Deprecation

The [ExchangeV2s](https://shopify.dev/docs/apps/build/pos/exchangesv2) API should no longer be used for new integrations, and is deprecated and pending removal [after our support period](https://shopify.dev/docs/api/usage/versioning#deprecation-practices) ends. The [`Order.returns()`](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/ReturnConnection) API is a replacement for this API. We plan on removing the ExchangeV2s API in the 2026-04 version.

As of API version 2025-04, the `Order.exchangeV2s()` API has an [additional query parameter](https://shopify.dev/changelog/new-includemirroredexchanges-query-filter-parameter) `include_mirrored_exchanges` which defaults to `true`. When the query parameter is true, the API will include Admin exchanges. If the query parameter is set to false, it will exclude exchanges initiated from Admin and only include exchanges initiated from POS.

A future version of POS will stop creating ExchangeV2s and will instead directly create exchanges with the Shopify returns platform. The query parameter is there to ensure that when POS changes over to creating those exchanges directly you will still be able to see them in existing ExchangeV2 API integrations.

## Integration

We expect that integrations will stop calling the `Order.exchangeV2s()` API, and instead invoke the [`Order.returns()`](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/ReturnConnection) API. POS now creates exchanges that are visible via that API.

Previous integrations would query the Order API with something like:

```
query GetOrderExchangeV2s {
  order(id: "gid://shopify/Order/1234567890") {
    exchangeV2s(first:10) {
      edges {
        node {
          id
          # additional fields
        }
      }
    }
  }
}
```

In the future, integrations should query the Order API with something like:

```
query GetOrderExchanges {
  order(id: "gid://shopify/Order/1234567890") {
    returns(first:10) {
      edges {
        node {
          id
          # additional fields
        }
      }
    }
  }
}
```

Note that `Order.returns()` will fetch both returns and exchanges. On the [ExchangeV2 API](https://shopify.dev/docs/apps/build/pos/exchangesv2#exchangev2s-related-graphql-objects), exchanged and returned items were present on the `additions` and `returns` fields. On the [Return API](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/Return) however, the `returnLineItems` field contains the items that are being returned, and the `exchangeLineItems` field contains the items that are being added to the order in exchange.

## Migration Strategy

To aid your migration over to the Platform APIs and off ExchangeV2 APIs, we suggest the following migration strategy:

1. In pipelines that consume `Order.exchangeV2s()`, set `include_mirrored_exchanges:false` in the query parameter if you want to exclude exchanges created via Admin.
2. Begin consuming `Order.returns()` data in your ETL pipelines
3. Stop consuming `Order.exchangeV2s()` API