Skip to main content

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.

Anchor to DeprecationDeprecation

The ExchangeV2s API should no longer be used for new integrations, and is deprecated and pending removal after our support period ends. The Order.returns() 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 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.

Anchor to IntegrationIntegration

We expect that integrations will stop calling the Order.exchangeV2s() API, and instead invoke the Order.returns() 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, exchanged and returned items were present on the additions and returns fields. On the Return API 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.

Anchor to Migration StrategyMigration 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
Was this page helpful?