Choose a version:

orderRequestReturn

mutation

Requires customer_write_customers access scope.

Request a new return on behalf of a customer.

Anchor to Arguments

Arguments

Anchor to orderIdorderId

•ID!

required

The ID of the order for which this return is being requested.

Anchor to requestedLineItemsrequestedLineItems

•[RequestedLineItemInput!]!

required

The line items that are requested to be returned.

Show input fields

Was this section helpful?

Anchor to OrderRequestReturnPayload returnsOrderRequestReturnPayload returns

Anchor to returnreturn •Return: The return request that has been made.

Show fields
Anchor to userErrorsuserErrors •[ReturnUserError!]! non-null: The list of errors that occurred from executing the mutation.

Show fields

Was this section helpful?

Examples

Request a return with a return reason definition

Description

Request a return on behalf of a customer using the new `returnReasonDefinitionId` field. This example demonstrates how to specify a standardized return reason when requesting a return through the Customer API. The `returnReasonDefinitionId` should be obtained from available return reason definitions.

Query

mutation orderRequestReturn($orderId: ID!, $requestedLineItems: [RequestedLineItemInput!]!) {
  orderRequestReturn(orderId: $orderId, requestedLineItems: $requestedLineItems) {
    return {
      id
      status
      returnLineItems(first: 10) {
        edges {
          node {
            id
            quantity
            returnReasonDefinition {
              handle
              name
              deleted
            }
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Variables

{
  "orderId": "gid://shopify/Order/569035839",
  "requestedLineItems": [
    {
      "lineItemId": "gid://shopify/LineItem/353882977",
      "quantity": 1,
      "returnReasonDefinitionId": "gid://shopify/ReturnReasonDefinition/640710815",
      "customerNote": "The item doesn't fit as expected"
    }
  ]
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/customer/api/unstable/graphql \
-H 'Content-Type: application/json' \
-H 'Authorization: {access_token}' \
-d '{
"query": "mutation orderRequestReturn($orderId: ID!, $requestedLineItems: [RequestedLineItemInput!]!) { orderRequestReturn(orderId: $orderId, requestedLineItems: $requestedLineItems) { return { id status returnLineItems(first: 10) { edges { node { id quantity returnReasonDefinition { handle name deleted } } } } } userErrors { field message } } }",
 "variables": {
    "orderId": "gid://shopify/Order/569035839",
    "requestedLineItems": [
      {
        "lineItemId": "gid://shopify/LineItem/353882977",
        "quantity": 1,
        "returnReasonDefinitionId": "gid://shopify/ReturnReasonDefinition/640710815",
        "customerNote": "The item doesn'\''t fit as expected"
      }
    ]
  }
}'

Response

{
  "orderRequestReturn": {
    "return": {
      "id": "gid://shopify/Return/963805104",
      "status": "REQUESTED",
      "returnLineItems": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/ReturnLineItem/791246336",
              "quantity": 1,
              "returnReasonDefinition": {
                "handle": "too-small",
                "name": "Too Small",
                "deleted": false
              }
            }
          }
        ]
      }
    },
    "userErrors": []
  }
}

orderRequestReturn reference

Examples

mutation orderRequestReturn($orderId: ID!, $requestedLineItems: [RequestedLineItemInput!]!) {

orderRequestReturn(orderId: $orderId, requestedLineItems: $requestedLineItems) {

return {

status

returnLineItems(first: 10) {

edges {

node {

quantity

returnReasonDefinition {

handle

name

deleted

}

userErrors {

field

message

}

GQL

mutation orderRequestReturn($orderId: ID!, $requestedLineItems: [RequestedLineItemInput!]!) {
  orderRequestReturn(orderId: $orderId, requestedLineItems: $requestedLineItems) {
    return {
      id
      status
      returnLineItems(first: 10) {
        edges {
          node {
            id
            quantity
            returnReasonDefinition {
              handle
              name
              deleted
            }
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/customer/api/unstable/graphql \
-H 'Content-Type: application/json' \
-H 'Authorization: {access_token}' \
-d '{
"query": "mutation orderRequestReturn($orderId: ID!, $requestedLineItems: [RequestedLineItemInput!]!) { orderRequestReturn(orderId: $orderId, requestedLineItems: $requestedLineItems) { return { id status returnLineItems(first: 10) { edges { node { id quantity returnReasonDefinition { handle name deleted } } } } } userErrors { field message } } }",
 "variables": {
    "orderId": "gid://shopify/Order/569035839",
    "requestedLineItems": [
      {
        "lineItemId": "gid://shopify/LineItem/353882977",
        "quantity": 1,
        "returnReasonDefinitionId": "gid://shopify/ReturnReasonDefinition/640710815",
        "customerNote": "The item doesn'\''t fit as expected"
      }
    ]
  }
}'

Input variables

JSON

{

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

"requestedLineItems": [

{

"lineItemId": "gid://shopify/LineItem/353882977",

"quantity": 1,

"returnReasonDefinitionId": "gid://shopify/ReturnReasonDefinition/640710815",

"customerNote": "The item doesn't fit as expected"

}

]

}

Response

JSON

{

"orderRequestReturn": {

"return": {

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

"status": "REQUESTED",

"returnLineItems": {

"edges": [

{

"node": {

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

"quantity": 1,

"returnReasonDefinition": {

"handle": "too-small",

"name": "Too Small",

"deleted": false

}

]

}

"userErrors": []

}