---
title: orderRequestReturn - Customer API
description: Request a new return on behalf of a customer.
api_version: 2026-01
api_name: customer
type: mutation
api_type: graphql
source_url:
  html: 'https://shopify.dev/docs/api/customer/latest/mutations/orderRequestReturn'
  md: 'https://shopify.dev/docs/api/customer/latest/mutations/orderRequestReturn.md'
---

# order​Request​Return

mutation

Request a new return on behalf of a customer.

## Arguments

* order​Id

  [ID!](https://shopify.dev/docs/api/customer/latest/scalars/ID)

  required

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

* requested​Line​Items

  [\[Requested​Line​Item​Input!\]!](https://shopify.dev/docs/api/customer/latest/input-objects/RequestedLineItemInput)

  required

  The line items that are requested to be returned.

***

## Order​Request​Return​Payload returns

* return

  [Return](https://shopify.dev/docs/api/customer/latest/objects/Return)

  The return request that has been made.

* user​Errors

  [\[Return​User​Error!\]!](https://shopify.dev/docs/api/customer/latest/objects/ReturnUserError)

  non-null

  The list of errors that occurred from executing the mutation.

***

## 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

  ```graphql
  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

  ```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"
      }
    ]
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/customer/api/2026-01/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

  ```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": []
    }
  }
  ```

* ### orderRequestReturn reference

[Open in GraphiQL](http://localhost:3457/graphiql?query=mutation%20orderRequestReturn\(%24orderId%3A%20ID!%2C%20%24requestedLineItems%3A%20%5BRequestedLineItemInput!%5D!\)%20%7B%0A%20%20orderRequestReturn\(orderId%3A%20%24orderId%2C%20requestedLineItems%3A%20%24requestedLineItems\)%20%7B%0A%20%20%20%20return%20%7B%0A%20%20%20%20%20%20id%0A%20%20%20%20%20%20status%0A%20%20%20%20%20%20returnLineItems\(first%3A%2010\)%20%7B%0A%20%20%20%20%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20id%0A%20%20%20%20%20%20%20%20%20%20%20%20quantity%0A%20%20%20%20%20%20%20%20%20%20%20%20returnReasonDefinition%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20handle%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20name%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20deleted%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%20%20userErrors%20%7B%0A%20%20%20%20%20%20field%0A%20%20%20%20%20%20message%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D\&variables=%7B%0A%20%20%22orderId%22%3A%20%22gid%3A%2F%2Fshopify%2FOrder%2F569035839%22%2C%0A%20%20%22requestedLineItems%22%3A%20%5B%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%22lineItemId%22%3A%20%22gid%3A%2F%2Fshopify%2FLineItem%2F353882977%22%2C%0A%20%20%20%20%20%20%22quantity%22%3A%201%2C%0A%20%20%20%20%20%20%22returnReasonDefinitionId%22%3A%20%22gid%3A%2F%2Fshopify%2FReturnReasonDefinition%2F640710815%22%2C%0A%20%20%20%20%20%20%22customerNote%22%3A%20%22The%20item%20doesn't%20fit%20as%20expected%22%0A%20%20%20%20%7D%0A%20%20%5D%0A%7D)

##### GQL

```graphql
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

```bash
curl -X POST \
https://your-development-store.myshopify.com/customer/api/2026-01/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

```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

```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": []
  }
}
```