Skip to main content

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 object is the recommended approach for accessing exchange data. The legacy exchangeV2s field is being phased out in favor of this unified solution.

Anchor to Accessing exchange data through the ,[object Object], objectAccessing exchange data through the Return object

Refer to our docs 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.

Anchor to Update your queriesUpdate your queries

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

Anchor to Before, using the ,[object Object], objectBefore, using the ExchangeV2 object

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

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

Anchor to After, using the ,[object Object], objectAfter, 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 for more details.

Query returns on an order

GraphQL query

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

{
"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" }
}
}
}]
}
}
}]
}
}
}
}

Anchor to Best practicesBest practices

  • Use the 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.
  • Query returns at the order level: Get all returns/exchanges for an order in one query.

Anchor to Additional resourcesAdditional resources

Was this page helpful?