---
title: return - GraphQL Admin
description: |-
  Retrieves a return by its ID. A return represents the intent of a buyer to ship one or more items from an
  order back to a merchant or a third-party fulfillment location.

  Use the `return` query to retrieve information associated with the following workflows:

  - [Managing returns](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management)
  - [Processing exchanges](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-exchanges)
  - [Tracking reverse fulfillment orders](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders)

  A return is associated with an
  [order](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order)
  and can include multiple return [line items](https://shopify.dev/docs/api/admin-graphql/latest/objects/LineItem).
  Each return has a [status](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps#return-statuses),
  which indicates the state of the return.
api_version: 2025-10
api_name: admin
type: query
api_type: graphql
source_url:
  html: https://shopify.dev/docs/api/admin-graphql/latest/queries/return
  md: https://shopify.dev/docs/api/admin-graphql/latest/queries/return.md
---

# return

query

Requires `read_returns` access scope or `read_marketplace_returns` access scope.

Retrieves a return by its ID. A return represents the intent of a buyer to ship one or more items from an order back to a merchant or a third-party fulfillment location.

Use the `return` query to retrieve information associated with the following workflows:

* [Managing returns](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management)
* [Processing exchanges](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-exchanges)
* [Tracking reverse fulfillment orders](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders)

A return is associated with an [order](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) and can include multiple return [line items](https://shopify.dev/docs/api/admin-graphql/latest/objects/LineItem). Each return has a [status](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps#return-statuses), which indicates the state of the return.

## Arguments

* id

  [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID)

  required

  The [globally-unique ID](https://shopify.dev/docs/api/usage/gids) of the return to retrieve.

***

## Possible returns

* Return

  [Return](https://shopify.dev/docs/api/admin-graphql/latest/objects/Return)

  The `Return` object represents the intent of a buyer to ship one or more items from an order back to a merchant or a third-party fulfillment location. A return is associated with an [order](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) and can include multiple return [line items](https://shopify.dev/docs/api/admin-graphql/latest/objects/LineItem). Each return has a [status](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps#return-statuses), which indicates the state of the return.

  Use the `Return` object to capture the financial, logistical, and business intent of a return. For example, you can identify eligible items for a return and issue customers a refund for returned items on behalf of the merchant.

  Learn more about providing a [return management workflow](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management) for merchants. You can also manage [exchanges](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-exchanges), [reverse fulfillment orders](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders), and [reverse deliveries](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-deliveries) on behalf of merchants.

***

## Examples

* ### Retrieve a return's exchange line items

  #### Description

  Retrieve the exchange line items associated with a return to access which items are being exchanged as part of a return process. This example shows how to query for the \`exchangeLineItems\` connection, which includes the IDs of the exchange line items. Learn more about \[managing exchanges]\(https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-exchanges).

  #### Query

  ```graphql
  query {
    return(id: "gid://shopify/Return/194950309") {
      exchangeLineItems(first: 10) {
        edges {
          node {
            id
          }
        }
      }
    }
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "query { return(id: \"gid://shopify/Return/194950309\") { exchangeLineItems(first: 10) { edges { node { id } } } } }"
  }'
  ```

  #### React Router

  ```javascript
  import { authenticate } from "../shopify.server";

  export const loader = async ({request}) => {
    const { admin } = await authenticate.admin(request);
    const response = await admin.graphql(
      `#graphql
    query {
      return(id: "gid://shopify/Return/194950309") {
        exchangeLineItems(first: 10) {
          edges {
            node {
              id
            }
          }
        }
      }
    }`,
    );
    const json = await response.json();
    return json.data;
  }
  ```

  #### Ruby

  ```ruby
  session = ShopifyAPI::Auth::Session.new(
    shop: "your-development-store.myshopify.com",
    access_token: access_token
  )
  client = ShopifyAPI::Clients::Graphql::Admin.new(
    session: session
  )

  query = <<~QUERY
    query {
      return(id: "gid://shopify/Return/194950309") {
        exchangeLineItems(first: 10) {
          edges {
            node {
              id
            }
          }
        }
      }
    }
  QUERY

  response = client.query(query: query)
  ```

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: `query {
      return(id: "gid://shopify/Return/194950309") {
        exchangeLineItems(first: 10) {
          edges {
            node {
              id
            }
          }
        }
      }
    }`,
  });
  ```

  #### Response

  ```json
  {
    "return": {
      "exchangeLineItems": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/ExchangeLineItem/444766497"
            }
          }
        ]
      }
    }
  }
  ```

* ### Retrieve a return's reverse fulfillment orders

  #### Description

  Retrieve the reverse fulfillment orders associated with a return. This example shows how to query the \`reverseFulfillmentOrders\` connection to get the IDs of related reverse fulfillment orders, which are used for tracking the logistics of returned items. Learn more about \[managing reverse fulfillment orders]\(https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders).

  #### Query

  ```graphql
  query {
    return(id: "gid://shopify/Return/684888505") {
      reverseFulfillmentOrders(first: 10) {
        edges {
          node {
            id
          }
        }
      }
    }
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "query { return(id: \"gid://shopify/Return/684888505\") { reverseFulfillmentOrders(first: 10) { edges { node { id } } } } }"
  }'
  ```

  #### React Router

  ```javascript
  import { authenticate } from "../shopify.server";

  export const loader = async ({request}) => {
    const { admin } = await authenticate.admin(request);
    const response = await admin.graphql(
      `#graphql
    query {
      return(id: "gid://shopify/Return/684888505") {
        reverseFulfillmentOrders(first: 10) {
          edges {
            node {
              id
            }
          }
        }
      }
    }`,
    );
    const json = await response.json();
    return json.data;
  }
  ```

  #### Ruby

  ```ruby
  session = ShopifyAPI::Auth::Session.new(
    shop: "your-development-store.myshopify.com",
    access_token: access_token
  )
  client = ShopifyAPI::Clients::Graphql::Admin.new(
    session: session
  )

  query = <<~QUERY
    query {
      return(id: "gid://shopify/Return/684888505") {
        reverseFulfillmentOrders(first: 10) {
          edges {
            node {
              id
            }
          }
        }
      }
    }
  QUERY

  response = client.query(query: query)
  ```

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: `query {
      return(id: "gid://shopify/Return/684888505") {
        reverseFulfillmentOrders(first: 10) {
          edges {
            node {
              id
            }
          }
        }
      }
    }`,
  });
  ```

  #### Response

  ```json
  {
    "return": {
      "reverseFulfillmentOrders": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/ReverseFulfillmentOrder/874405546"
            }
          }
        ]
      }
    }
  }
  ```

* ### Retrieve a return's status and line items

  #### Description

  Retrieve the status and the first ten return line items associated with a return. The example shows how to structure the query to access the return's name, order ID, and the relevant attributes of the return line items, such as quantity, return reason, and total weight. The return status is \`OPEN\`, which indicates tha the query was successfully executed. The example uses the \`... on ReturnLineItem\` \[fragment]\(https://shopify.dev/docs/apps/build/graphql/basics/advanced#inline-fragments) to access fields that only exist on the \[\`ReturnLineItem\`]\(https://shopify.dev/docs/api/admin-graphql/latest/objects/ReturnLineItem) object.

  #### Query

  ```graphql
  query {
    return(id: "gid://shopify/Return/945000954") {
      status
      name
      order {
        id
      }
      returnLineItems(first: 10) {
        edges {
          node {
            ... on ReturnLineItem {
              quantity
              returnReason
              returnReasonNote
              fulfillmentLineItem {
                lineItem {
                  name
                }
              }
              totalWeight {
                value
              }
            }
          }
        }
      }
    }
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "query { return(id: \"gid://shopify/Return/945000954\") { status name order { id } returnLineItems(first: 10) { edges { node { ... on ReturnLineItem { quantity returnReason returnReasonNote fulfillmentLineItem { lineItem { name } } totalWeight { value } } } } } } }"
  }'
  ```

  #### React Router

  ```javascript
  import { authenticate } from "../shopify.server";

  export const loader = async ({request}) => {
    const { admin } = await authenticate.admin(request);
    const response = await admin.graphql(
      `#graphql
    query {
      return(id: "gid://shopify/Return/945000954") {
        status
        name
        order {
          id
        }
        returnLineItems(first: 10) {
          edges {
            node {
              ... on ReturnLineItem {
                quantity
                returnReason
                returnReasonNote
                fulfillmentLineItem {
                  lineItem {
                    name
                  }
                }
                totalWeight {
                  value
                }
              }
            }
          }
        }
      }
    }`,
    );
    const json = await response.json();
    return json.data;
  }
  ```

  #### Ruby

  ```ruby
  session = ShopifyAPI::Auth::Session.new(
    shop: "your-development-store.myshopify.com",
    access_token: access_token
  )
  client = ShopifyAPI::Clients::Graphql::Admin.new(
    session: session
  )

  query = <<~QUERY
    query {
      return(id: "gid://shopify/Return/945000954") {
        status
        name
        order {
          id
        }
        returnLineItems(first: 10) {
          edges {
            node {
              ... on ReturnLineItem {
                quantity
                returnReason
                returnReasonNote
                fulfillmentLineItem {
                  lineItem {
                    name
                  }
                }
                totalWeight {
                  value
                }
              }
            }
          }
        }
      }
    }
  QUERY

  response = client.query(query: query)
  ```

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: `query {
      return(id: "gid://shopify/Return/945000954") {
        status
        name
        order {
          id
        }
        returnLineItems(first: 10) {
          edges {
            node {
              ... on ReturnLineItem {
                quantity
                returnReason
                returnReasonNote
                fulfillmentLineItem {
                  lineItem {
                    name
                  }
                }
                totalWeight {
                  value
                }
              }
            }
          }
        }
      }
    }`,
  });
  ```

  #### Response

  ```json
  {
    "return": {
      "status": "OPEN",
      "name": "#1001-R1",
      "order": {
        "id": "gid://shopify/Order/625362839"
      },
      "returnLineItems": {
        "edges": [
          {
            "node": {
              "quantity": 1,
              "returnReason": "UNKNOWN",
              "returnReasonNote": "",
              "fulfillmentLineItem": {
                "lineItem": {
                  "name": "Draft - 151cm"
                }
              },
              "totalWeight": {
                "value": 1500
              }
            }
          }
        ]
      }
    }
  }
  ```

[Open in GraphiQL](http://localhost:3457/graphiql?query=query%20%7B%0A%20%20return\(id%3A%20%22gid%3A%2F%2Fshopify%2FReturn%2F194950309%22\)%20%7B%0A%20%20%20%20exchangeLineItems\(first%3A%2010\)%20%7B%0A%20%20%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20%20%20id%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D)

```javascript
import { authenticate } from "../shopify.server";


export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query {
    return(id: "gid://shopify/Return/194950309") {
      exchangeLineItems(first: 10) {
        edges {
          node {
            id
          }
        }
      }
    }
  }`,
  );
  const json = await response.json();
  return json.data;
}
```

##### GQL

```
query {
  return(id: "gid://shopify/Return/194950309") {
    exchangeLineItems(first: 10) {
      edges {
        node {
          id
        }
      }
    }
  }
}
```

##### cURL

```
curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { return(id: \"gid://shopify/Return/194950309\") { exchangeLineItems(first: 10) { edges { node { id } } } } }"
}'
```

##### React Router

```
import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query {
    return(id: "gid://shopify/Return/194950309") {
      exchangeLineItems(first: 10) {
        edges {
          node {
            id
          }
        }
      }
    }
  }`,
  );
  const json = await response.json();
  return json.data;
}
```

##### Node.js

```
const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    return(id: "gid://shopify/Return/194950309") {
      exchangeLineItems(first: 10) {
        edges {
          node {
            id
          }
        }
      }
    }
  }`,
});
```

##### Ruby

```
session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query {
    return(id: "gid://shopify/Return/194950309") {
      exchangeLineItems(first: 10) {
        edges {
          node {
            id
          }
        }
      }
    }
  }
QUERY

response = client.query(query: query)
```

## Response

JSON

```json
{
  "return": {
    "exchangeLineItems": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/ExchangeLineItem/444766497"
          }
        }
      ]
    }
  }
}
```