---
title: Integration with the `Return` object for exchanges
description: Learn how to query returns and exchanges, access transaction data, and subscribe to return webhooks using the GraphQL Admin API.
source_url:
  html: https://shopify.dev/docs/apps/build/pos/exchangesv2
  md: https://shopify.dev/docs/apps/build/pos/exchangesv2.md
---

# Integration with the \`Return\` object for exchanges

The GraphQL Admin API provides comprehensive access to return and exchange data through the `Return` object and related fields. This approach eliminates the need for special access requests and provides a unified way to access returns and exchanges data created on both the Shopify admin and POS.

The `Return` object includes transaction data, simplifying the process of identifying and reconciling payments and refunds associated with exchanges. This document provides details on how to query return and exchange data using the GraphQL Admin API.

For ERP integrations, third-party connectors, or custom integrations of any kind, the recommended approach is to query the `Return` object because it provides standard API access without requiring special permissions, offers a unified data model for both returns and exchanges, and includes comprehensive transaction data for simplified financial reconciliation.

**Note:**

Querying the [`Return`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Return) object is the recommended approach for accessing exchange data. The legacy `exchangeV2s` field is being phased out in favor of this unified solution.

***

## Accessing exchange data through the `Return` object

[Refer to our docs](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/read-exchanges) for information on how to read exchange returns data, such as:

* Querying returns and exchanges.
* Understanding return and exchange line items.
* Accessing transaction data.
* Working with financial summaries.
* Webhooks.

***

## Update your queries

If you're currently using the `exchangeV2s` field, here's how to query the same data:

### Before, using the `ExchangeV2` object

This query retrieves the return and exchange line items for the first 10 exchanges associated with a particular order.

```graphql
query {
  order(id: "gid://shopify/Order/123") {
    exchangeV2s(first: 10) {
      edges {
        node {
          id
          additions {
            lineItems {
              quantity
              name
            }
          }
          returns {
            lineItems {
              quantity
              name
            }
          }
        }
      }
    }
  }
}
```

### After, using the `Return` object

This query retrieves the return line items, exchange line items, and transactions for the first 10 returns associated with a particular order.

**Note:**

The transactions connection is populated for the following scenarios:

* **POS returns and exchanges**: Includes both refunds and captured payments.
* **Online returns and exchanges**: Includes refunds only.

Read the [changelog entry on transaction access](https://shopify.dev/changelog/access-transactions-on-the-return-object) for more details.

## Query returns on an order

## GraphQL query

```graphql
query {
  order(id: "gid://shopify/Order/123") {
    returns(first: 10) {
      edges {
        node {
          id
          # Items being returned
          returnLineItems(first: 50) {
            edges {
              node {
                quantity
                lineItem {
                  name
                }
              }
            }
          }
          # New items (exchanges)
          exchangeLineItems(first: 50) {
            edges {
              node {
                quantity
                lineItem {
                  name
                }
              }
            }
          }
          # Associated transactions
          transactions(first: 10) {
            edges {
              node {
                id
                kind
                amountSet {
                  shopMoney {
                    amount
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "order": {
      "returns": {
        "edges": [{
          "node": {
            "id": "gid://shopify/Return/456",
            "returnLineItems": {
              "edges": [{
                "node": {
                  "quantity": 1,
                  "lineItem": { "name": "Medium Blue T-Shirt" }
                }
              }]
            },
            "exchangeLineItems": {
              "edges": [{
                "node": {
                  "quantity": 1,
                  "lineItem": { "name": "Large Blue T-Shirt" }
                }
              }]
            },
            "transactions": {
              "edges": [{
                "node": {
                  "id": "gid://shopify/OrderTransaction/789",
                  "kind": "SALE",
                  "amountSet": {
                    "shopMoney": { "amount": "5.00" }
                  }
                }
              }]
            }
          }
        }]
      }
    }
  }
}
```

***

## Best practices

* **Use the [`Return`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Return) object for all new integrations**: It provides comprehensive access without special permissions.
* **Check for `exchangeLineItems` to identify exchanges**: If present, then the return is an exchange.
* **Use `transactions` for financial reconciliation**: Direct transaction access via the `Return` object eliminates the guesswork involved in matching a transaction from the `Order` object to a specific return or exchange.
* **Subscribe to return webhooks**: Get real-time updates on return and exchange status, for example [`returns/process`](https://shopify.dev/docs/api/webhooks/2025-10?accordionItem=webhooks-returns-process\&reference=toml).
* **Query returns at the order level**: Get all returns/exchanges for an order in one query.

***

## Additional resources

* Learn more about the [`Return` object](https://shopify.dev/docs/api/admin-graphql/latest/objects/Return).
* Learn more about accessing the [returns for an `Order` object](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order#returns).
* Subscribe to [return webhooks](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps#webhooks) for real-time updates.
* Learn how to [manage returns](https://shopify.dev/docs/apps/build/orders-fulfillment/returns).
* Read the [changelog entry on transaction access](https://shopify.dev/changelog/access-transactions-on-the-return-object).

***