Choose a version:

return

query

Requires read_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.

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.

Was this section helpful?

Get status and return line items for a return
Get status and return line items for a return (API Version 2024-04 and older)

Examples

Open in GraphiQL

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

query {

return(id: "gid://shopify/Return/945000954") {

status

name

order {

}

returnLineItems(first: 10) {

edges {

node {

... on ReturnLineItem {

fulfillmentLineItem {

lineItem {

name

}

totalWeight {

value

}

quantity

returnReason

returnReasonNote

}

}`,

);

const data = await response.json();

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

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2024-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 { fulfillmentLineItem { lineItem { name } } totalWeight { value } } quantity returnReason returnReasonNote } } } } }"
}'

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 {
              fulfillmentLineItem {
                lineItem {
                  name
                }
              }
              totalWeight {
                value
              }
            }
            quantity
            returnReason
            returnReasonNote
          }
        }
      }
    }
  }`,
);

const data = await response.json();

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 {
              fulfillmentLineItem {
                lineItem {
                  name
                }
              }
              totalWeight {
                value
              }
            }
            quantity
            returnReason
            returnReasonNote
          }
        }
      }
    }
  }`,
});

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 {
              fulfillmentLineItem {
                lineItem {
                  name
                }
              }
              totalWeight {
                value
              }
            }
            quantity
            returnReason
            returnReasonNote
          }
        }
      }
    }
  }
QUERY

response = client.query(query: query)

Response

JSON

{

"return": {

"status": "OPEN",

"name": "#1001-R1",

"order": {

"id": "gid://shopify/Order/625362839"

"returnLineItems": {

"edges": [

{

"node": {

"fulfillmentLineItem": {

"lineItem": {

"name": "Draft - 151cm"

}

"totalWeight": {

"value": 1500

"quantity": 1,

"returnReason": "UNKNOWN",

"returnReasonNote": ""

}

]

}