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

# order​Request​Return

mutation

Requires `customer_write_customers` access scope.

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-10/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