Choose a version:

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:

A return is associated with an order and can include multiple return line items. Each return has a status, which indicates the state of the return.

Anchor to Arguments

Arguments

Anchor to idid •ID! required: The globally-unique ID of the return to retrieve.

Was this section helpful?

Anchor to Possible returnsPossible returns

Anchor to ReturnReturn

•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 and can include multiple return line items. Each return has a status, 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 for merchants. You can also manage exchanges, reverse fulfillment orders, and reverse deliveries on behalf of merchants.

Anchor to declinedecline

•ReturnDecline

Additional information about the declined return.

Anchor to exchangeLineItemsexchangeLineItems

•ExchangeLineItemConnection!

non-null

The exchange line items attached to the return.

Anchor to includeRemovedItemsincludeRemovedItems •Boolean Default:false: Include exchange line items that have been removed from the order by an order edit, return, etc. Items that have been removed have a zero (LineItem.currentQuantity).
Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to idid

•ID!

non-null

A globally-unique ID.

Anchor to namename

•String!

non-null

The name of the return.

Anchor to orderorder

•Order!

non-null

The order that the return belongs to.

Anchor to refundsrefunds

•RefundConnection!

non-null

The list of refunds associated with the return.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to returnLineItemsreturnLineItems

•ReturnLineItemTypeConnection!

non-null

The return line items attached to the return.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to returnShippingFeesreturnShippingFees

•[ReturnShippingFee!]!

non-null

The return shipping fees for the return.

Anchor to reverseFulfillmentOrdersreverseFulfillmentOrders

•ReverseFulfillmentOrderConnection!

non-null

The list of reverse fulfillment orders for the return.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to statusstatus

•ReturnStatus!

non-null

The status of the return.

Anchor to totalQuantitytotalQuantity

•Int!

non-null

The sum of all return line item quantities for the return.

Anchor to suggestedRefundsuggestedRefund

•SuggestedReturnRefund

Deprecated

Arguments

Anchor to returnRefundLineItemsreturnRefundLineItems

•[ReturnRefundLineItemInput!]!

required

The line items from the return to include in the refund.

Anchor to refundShippingrefundShipping

•RefundShippingInput

The shipping amount from the associated order to include in the refund.

Anchor to refundDutiesrefundDuties

•[RefundDutyInput!]

The duties from to associated order to include in the refund.

Was this section helpful?

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

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-04/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;
}

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

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
          }
        }
      }
    }
  }`,
});

Shopify CLI

shopify app execute \
--query \
'query {
  return(id: "gid://shopify/Return/194950309") {
    exchangeLineItems(first: 10) {
      edges {
        node {
          id
        }
      }
    }
  }
}'

Response

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

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-04/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

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

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

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
          }
        }
      }
    }
  }`,
});

Shopify CLI

shopify app execute \
--query \
'query {
  return(id: "gid://shopify/Return/684888505") {
    reverseFulfillmentOrders(first: 10) {
      edges {
        node {
          id
        }
      }
    }
  }
}'

Response

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

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

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-04/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

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

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

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
              }
            }
          }
        }
      }
    }
  }`,
});

Shopify CLI

shopify app execute \
--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
            }
          }
        }
      }
    }
  }
}'

Response

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

Examples

Open in GraphiQL

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 {

}

}`,

);

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-04/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)

Shopify CLI

shopify app execute \
--query \
'query {
  return(id: "gid://shopify/Return/194950309") {
    exchangeLineItems(first: 10) {
      edges {
        node {
          id
        }
      }
    }
  }
}'

Response

JSON

{

"return": {

"exchangeLineItems": {

"edges": [

{

"node": {

"id": "gid://shopify/ExchangeLineItem/444766497"

}

]

}