Requires write_returns access scope or write_marketplace_returns access scope. Also: Requires the write_orders access scope. The user must have return_orders permission.
A customer's return request that hasn't been approved or declined.
This mutation sets the value of the Return.status field to REQUESTED.
To create a return that has the Return.status field set to OPEN, use the returnCreate mutation.
The list of errors that occurred from executing the mutation.
Was this section helpful?
Examples
Hide code
DescriptionCopy
mutation ReturnRequest($input: ReturnRequestInput!) {
returnRequest(input: $input) {
userErrors {
field
message
}
return {
id
status
returnLineItems(first: 1) {
edges {
node {
id
returnReason
customerNote
}
}
}
order {
id
}
}
}
}
curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-01/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?"
}
]
}
}
}'
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 data = await response.json();
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)
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?"
}
]
}
},
},
});
use Shopify\Clients\Graphql;
$client = new Graphql("your-development-store.myshopify.com", $accessToken);
$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]);
Hide code
Input variables
Copy
{
"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?"
}
]
}
}
Hide code
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"
}
}
}
}