Choose a version:

returnRequest

mutation

Requires write_returns access scope or write_marketplace_returns access scope.

Creates a return request that requires merchant approval before processing. The return has its status set to REQUESTED and the merchant must approve or decline it.

Use this mutation when customers initiate returns that need review. After creating a requested return, use returnApproveRequest to approve it or returnDeclineRequest to decline it.

For returns that should be immediately open for processing, use the returnCreate mutation instead.

Learn more about building return management workflows.

Anchor to Arguments

Arguments

Anchor to inputinput •ReturnRequestInput! required: The input fields for requesting a return.

Was this section helpful?

Anchor to ReturnRequestPayload returnsReturnRequestPayload returns

Anchor to returnreturn •Return: The requested return.
Anchor to userErrorsuserErrors •[ReturnUserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Request a return

Description

Request a return for the order.

Query

mutation ReturnRequest($input: ReturnRequestInput!) {
  returnRequest(input: $input) {
    userErrors {
      field
      message
    }
    return {
      id
      status
      returnLineItems(first: 1) {
        edges {
          node {
            id
            returnReason
            customerNote
          }
        }
      }
      order {
        id
      }
    }
  }
}

Variables

{
  "input": {
    "orderId": "gid://shopify/Order/625362839",
    "returnLineItems": [
      {
        "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
        "quantity": 1,
        "returnReason": "WRONG_ITEM",
        "customerNote": "Sorry, I ordered the wrong item. Could I get a refund or store credit?"
      }
    ]
  }
}

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": "mutation ReturnRequest($input: ReturnRequestInput!) { returnRequest(input: $input) { userErrors { field message } return { id status returnLineItems(first: 1) { edges { node { id returnReason customerNote } } } order { id } } } }",
 "variables": {
    "input": {
      "orderId": "gid://shopify/Order/625362839",
      "returnLineItems": [
        {
          "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
          "quantity": 1,
          "returnReason": "WRONG_ITEM",
          "customerNote": "Sorry, I ordered the wrong item. Could I get a refund or store credit?"
        }
      ]
    }
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation ReturnRequest($input: ReturnRequestInput!) {
    returnRequest(input: $input) {
      userErrors {
        field
        message
      }
      return {
        id
        status
        returnLineItems(first: 1) {
          edges {
            node {
              id
              returnReason
              customerNote
            }
          }
        }
        order {
          id
        }
      }
    }
  }`,
  {
    variables: {
        "input": {
            "orderId": "gid://shopify/Order/625362839",
            "returnLineItems": [
                {
                    "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
                    "quantity": 1,
                    "returnReason": "WRONG_ITEM",
                    "customerNote": "Sorry, I ordered the wrong item. Could I get a refund or store credit?"
                }
            ]
        }
    },
  },
  );
  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
  mutation ReturnRequest($input: ReturnRequestInput!) {
    returnRequest(input: $input) {
      userErrors {
        field
        message
      }
      return {
        id
        status
        returnLineItems(first: 1) {
          edges {
            node {
              id
              returnReason
              customerNote
            }
          }
        }
        order {
          id
        }
      }
    }
  }
QUERY

variables = {
  "input": {
    "orderId": "gid://shopify/Order/625362839",
    "returnLineItems": [
      {
        "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
        "quantity": 1,
        "returnReason": "WRONG_ITEM",
        "customerNote": "Sorry, I ordered the wrong item. Could I get a refund or store credit?"
      }
    ]
  }
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation ReturnRequest($input: ReturnRequestInput!) {
      returnRequest(input: $input) {
        userErrors {
          field
          message
        }
        return {
          id
          status
          returnLineItems(first: 1) {
            edges {
              node {
                id
                returnReason
                customerNote
              }
            }
          }
          order {
            id
          }
        }
      }
    }`,
    "variables": {
        "input": {
            "orderId": "gid://shopify/Order/625362839",
            "returnLineItems": [
                {
                    "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
                    "quantity": 1,
                    "returnReason": "WRONG_ITEM",
                    "customerNote": "Sorry, I ordered the wrong item. Could I get a refund or store credit?"
                }
            ]
        }
    },
  },
});

Response

{
  "returnRequest": {
    "userErrors": [],
    "return": {
      "id": "gid://shopify/Return/945000961",
      "status": "REQUESTED",
      "returnLineItems": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/ReturnLineItem/677614678",
              "returnReason": "WRONG_ITEM",
              "customerNote": "Sorry, I ordered the wrong item. Could I get a refund or store credit?"
            }
          }
        ]
      },
      "order": {
        "id": "gid://shopify/Order/625362839"
      }
    }
  }
}

returnRequest reference

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

mutation ReturnRequest($input: ReturnRequestInput!) {

returnRequest(input: $input) {

userErrors {

field

message

}

return {

status

returnLineItems(first: 1) {

edges {

node {

returnReason

customerNote

}

order {

}

}`,

{

variables: {

"input": {

"orderId": "gid://shopify/Order/625362839",

"returnLineItems": [

{

"fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",

"quantity": 1,

"returnReason": "WRONG_ITEM",

"customerNote": "Sorry, I ordered the wrong item. Could I get a refund or store credit?"

}

]

}

);

const json = await response.json();

return json.data;

}

GQL

mutation ReturnRequest($input: ReturnRequestInput!) {
  returnRequest(input: $input) {
    userErrors {
      field
      message
    }
    return {
      id
      status
      returnLineItems(first: 1) {
        edges {
          node {
            id
            returnReason
            customerNote
          }
        }
      }
      order {
        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": "mutation ReturnRequest($input: ReturnRequestInput!) { returnRequest(input: $input) { userErrors { field message } return { id status returnLineItems(first: 1) { edges { node { id returnReason customerNote } } } order { id } } } }",
 "variables": {
    "input": {
      "orderId": "gid://shopify/Order/625362839",
      "returnLineItems": [
        {
          "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
          "quantity": 1,
          "returnReason": "WRONG_ITEM",
          "customerNote": "Sorry, I ordered the wrong item. Could I get a refund or store credit?"
        }
      ]
    }
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation ReturnRequest($input: ReturnRequestInput!) {
    returnRequest(input: $input) {
      userErrors {
        field
        message
      }
      return {
        id
        status
        returnLineItems(first: 1) {
          edges {
            node {
              id
              returnReason
              customerNote
            }
          }
        }
        order {
          id
        }
      }
    }
  }`,
  {
    variables: {
        "input": {
            "orderId": "gid://shopify/Order/625362839",
            "returnLineItems": [
                {
                    "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
                    "quantity": 1,
                    "returnReason": "WRONG_ITEM",
                    "customerNote": "Sorry, I ordered the wrong item. Could I get a refund or store credit?"
                }
            ]
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation ReturnRequest($input: ReturnRequestInput!) {
      returnRequest(input: $input) {
        userErrors {
          field
          message
        }
        return {
          id
          status
          returnLineItems(first: 1) {
            edges {
              node {
                id
                returnReason
                customerNote
              }
            }
          }
          order {
            id
          }
        }
      }
    }`,
    "variables": {
        "input": {
            "orderId": "gid://shopify/Order/625362839",
            "returnLineItems": [
                {
                    "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
                    "quantity": 1,
                    "returnReason": "WRONG_ITEM",
                    "customerNote": "Sorry, I ordered the wrong item. Could I get a refund or store credit?"
                }
            ]
        }
    },
  },
});

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
  mutation ReturnRequest($input: ReturnRequestInput!) {
    returnRequest(input: $input) {
      userErrors {
        field
        message
      }
      return {
        id
        status
        returnLineItems(first: 1) {
          edges {
            node {
              id
              returnReason
              customerNote
            }
          }
        }
        order {
          id
        }
      }
    }
  }
QUERY

variables = {
  "input": {
    "orderId": "gid://shopify/Order/625362839",
    "returnLineItems": [
      {
        "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
        "quantity": 1,
        "returnReason": "WRONG_ITEM",
        "customerNote": "Sorry, I ordered the wrong item. Could I get a refund or store credit?"
      }
    ]
  }
}

response = client.query(query: query, variables: variables)

Input variables

JSON

{

"input": {

"orderId": "gid://shopify/Order/625362839",

"returnLineItems": [

{

"fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",

"quantity": 1,

"returnReason": "WRONG_ITEM",

"customerNote": "Sorry, I ordered the wrong item. Could I get a refund or store credit?"

}

]

}

Response

JSON

{

"returnRequest": {

"userErrors": [],

"return": {

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

"status": "REQUESTED",

"returnLineItems": {

"edges": [

{

"node": {

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

"returnReason": "WRONG_ITEM",

"customerNote": "Sorry, I ordered the wrong item. Could I get a refund or store credit?"

}

]

"order": {

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

}