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 closedAtclosedAt

•DateTime

The date and time when the return was closed.

Anchor to createdAtcreatedAt

•DateTime!

non-null

The date and time when the return was created.

Anchor to declinedecline

•ReturnDecline

Additional information about the declined return.

Anchor to exchangeLineItemsexchangeLineItems

•ExchangeLineItemConnection!

non-null

The exchange line items attached to the return.

Arguments

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 processingStatusprocessingStatus

•ReturnProcessingStatusFilterInput

Filter exchange line items by processing status.

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 requestApprovedAtrequestApprovedAt

•DateTime

The date and time when the return was approved.

Anchor to returnLineItemsreturnLineItems

•ReturnLineItemTypeConnection!

non-null

The return line items attached to the return.

Arguments

Anchor to processingStatusprocessingStatus

•ReturnProcessingStatusFilterInput

Filter return line items by processing status.

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 staffMemberstaffMember

•StaffMember

The staff member that created the return.

Anchor to statusstatus

•ReturnStatus!

non-null

The status of the return.

Anchor to suggestedFinancialOutcomesuggestedFinancialOutcome

•SuggestedReturnFinancialOutcome

A suggested financial outcome for the return.

Arguments

Anchor to returnLineItemsreturnLineItems

required

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

Anchor to exchangeLineItemsexchangeLineItems

required

The exchange line items from the return to include in the outcome.

Anchor to refundShippingrefundShipping

•RefundShippingInput

The shipping amount from the associated order to include as a refund.

Anchor to tipLineIdtipLineId

•ID

ID of the tip line item.

Anchor to refundDutiesrefundDuties

•[RefundDutyInput!]

The duties from the associated order to include as a refund.

Anchor to refundMethodAllocationrefundMethodAllocation

•RefundMethodAllocation

Default:ORIGINAL_PAYMENT_METHODS

Specifies which refund methods to allocate the suggested refund amount to.

Anchor to totalQuantitytotalQuantity

•Int!

non-null

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

Anchor to transactionstransactions

•OrderTransactionConnection!

non-null

The order transactions created from 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 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

Query return with return reason definitions

Description

Retrieve return line items with their associated return reason definitions. This example shows how to access standardized return reasons instead of the deprecated enum.

Query

query {
  return(id: "gid://shopify/Return/945000954") {
    id
    name
    returnLineItems(first: 5) {
      edges {
        node {
          id
          quantity
          returnReasonDefinition {
            id
            handle
            name
            deleted
          }
          customerNote
        }
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { return(id: \"gid://shopify/Return/945000954\") { id name returnLineItems(first: 5) { edges { node { id quantity returnReasonDefinition { id handle name deleted } customerNote } } } } }"
}'

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") {
      id
      name
      returnLineItems(first: 5) {
        edges {
          node {
            id
            quantity
            returnReasonDefinition {
              id
              handle
              name
              deleted
            }
            customerNote
          }
        }
      }
    }
  }`,
  );
  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") {
      id
      name
      returnLineItems(first: 5) {
        edges {
          node {
            id
            quantity
            returnReasonDefinition {
              id
              handle
              name
              deleted
            }
            customerNote
          }
        }
      }
    }
  }
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") {
      id
      name
      returnLineItems(first: 5) {
        edges {
          node {
            id
            quantity
            returnReasonDefinition {
              id
              handle
              name
              deleted
            }
            customerNote
          }
        }
      }
    }
  }`,
});

Response

{
  "return": {
    "id": "gid://shopify/Return/945000954",
    "name": "#1001-R1",
    "returnLineItems": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/ReturnLineItem/57615080",
            "quantity": 1,
            "returnReasonDefinition": {
              "id": "gid://shopify/ReturnReasonDefinition/305697940",
              "handle": "defective",
              "name": "Defective",
              "deleted": false
            },
            "customerNote": null
          }
        }
      ]
    }
  }
}

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

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

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

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/945000954") {

name

returnLineItems(first: 5) {

edges {

node {

quantity

returnReasonDefinition {

handle

name

deleted

}

customerNote

}

}`,

);

const json = await response.json();

return json.data;

}

GQL

query {
  return(id: "gid://shopify/Return/945000954") {
    id
    name
    returnLineItems(first: 5) {
      edges {
        node {
          id
          quantity
          returnReasonDefinition {
            id
            handle
            name
            deleted
          }
          customerNote
        }
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { return(id: \"gid://shopify/Return/945000954\") { id name returnLineItems(first: 5) { edges { node { id quantity returnReasonDefinition { id handle name deleted } customerNote } } } } }"
}'

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") {
      id
      name
      returnLineItems(first: 5) {
        edges {
          node {
            id
            quantity
            returnReasonDefinition {
              id
              handle
              name
              deleted
            }
            customerNote
          }
        }
      }
    }
  }`,
  );
  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/945000954") {
      id
      name
      returnLineItems(first: 5) {
        edges {
          node {
            id
            quantity
            returnReasonDefinition {
              id
              handle
              name
              deleted
            }
            customerNote
          }
        }
      }
    }
  }`,
});

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") {
      id
      name
      returnLineItems(first: 5) {
        edges {
          node {
            id
            quantity
            returnReasonDefinition {
              id
              handle
              name
              deleted
            }
            customerNote
          }
        }
      }
    }
  }
QUERY

response = client.query(query: query)

Response

JSON

{

"return": {

"id": "gid://shopify/Return/945000954",

"name": "#1001-R1",

"returnLineItems": {

"edges": [

{

"node": {

"id": "gid://shopify/ReturnLineItem/57615080",

"quantity": 1,

"returnReasonDefinition": {

"id": "gid://shopify/ReturnReasonDefinition/305697940",

"handle": "defective",

"name": "Defective",

"deleted": false

"customerNote": null

}

]

}