---
title: returnCreate - GraphQL Admin
description: |-
  Creates a return from an existing order that has at least one fulfilled
  [line item](https://shopify.dev/docs/api/admin-graphql/latest/objects/LineItem)
  that hasn't yet been refunded. If you create a return on an archived order, then the order is automatically
  unarchived.

  Use the `returnCreate` mutation when your workflow involves
  [approving](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnApproveRequest) or
  [declining](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnDeclineRequest) requested returns
  outside of the Shopify platform.

  The `returnCreate` mutation performs the following actions:

  - Creates a return in the `OPEN` state, and assumes that the return request from the customer has already been
  approved
  - Creates a [reverse fulfillment order](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders),
  and enables you to create a [reverse delivery](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-deliveries)
  for the reverse fulfillment order
  - Creates a sales agreement with a `RETURN` reason, which links to all sales created for the return or exchange
  - Generates sales records that reverse the sales records for the items being returned
  - Generates sales records for any exchange line items

  After you've created a return, use the
  [`return`](https://shopify.dev/docs/api/admin-graphql/latest/queries/return) query to retrieve the
  return by its ID. Learn more about providing a
  [return management workflow](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management)
  for merchants.
api_version: 2025-07
api_name: admin
type: mutation
api_type: graphql
source_url:
  html: https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/returnCreate
  md: https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/returnCreate.md
---

# return​Create

mutation

Requires `write_returns` access scope or `write_marketplace_returns` access scope.

Creates a return from an existing order that has at least one fulfilled [line item](https://shopify.dev/docs/api/admin-graphql/latest/objects/LineItem) that hasn't yet been refunded. If you create a return on an archived order, then the order is automatically unarchived.

Use the `returnCreate` mutation when your workflow involves [approving](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnApproveRequest) or [declining](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnDeclineRequest) requested returns outside of the Shopify platform.

The `returnCreate` mutation performs the following actions:

* Creates a return in the `OPEN` state, and assumes that the return request from the customer has already been approved
* Creates a [reverse fulfillment order](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders), and enables you to create a [reverse delivery](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-deliveries) for the reverse fulfillment order
* Creates a sales agreement with a `RETURN` reason, which links to all sales created for the return or exchange
* Generates sales records that reverse the sales records for the items being returned
* Generates sales records for any exchange line items

After you've created a return, use the [`return`](https://shopify.dev/docs/api/admin-graphql/latest/queries/return) query to retrieve the return by its ID. Learn more about providing a [return management workflow](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management) for merchants.

## Arguments

* return​Input

  [Return​Input!](https://shopify.dev/docs/api/admin-graphql/2025-07/input-objects/ReturnInput)

  required

  Specifies the input fields for a return.

***

## Return​Create​Payload returns

* return

  [Return](https://shopify.dev/docs/api/admin-graphql/2025-07/objects/Return)

  The created return.

* user​Errors

  [\[Return​User​Error!\]!](https://shopify.dev/docs/api/admin-graphql/2025-07/objects/ReturnUserError)

  non-null

  The list of errors that occurred from executing the mutation.

***

## Examples

* ### Create a return for a fulfilled line item

  #### Description

  Create a return for a fulfilled \[line item]\(https\://shopify.dev/docs/api/admin-graphql/latest/objects/LineItem) and include a custom reason note—a freeform note that allows the customer to explain their reason for returning the item. The example returns the created return's ID and the associated order ID. Learn more about \[building for return management]\(https\://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management).

  #### Query

  ```graphql
  mutation ReturnCreate($returnInput: ReturnInput!) {
    returnCreate(returnInput: $returnInput) {
      userErrors {
        field
        message
      }
      return {
        id
        order {
          id
        }
      }
    }
  }
  ```

  #### Variables

  ```json
  {
    "returnInput": {
      "orderId": "gid://shopify/Order/625362839",
      "returnLineItems": [
        {
          "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
          "quantity": 1,
          "returnReason": "SIZE_TOO_SMALL"
        }
      ]
    }
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "mutation ReturnCreate($returnInput: ReturnInput!) { returnCreate(returnInput: $returnInput) { userErrors { field message } return { id order { id } } } }",
   "variables": {
      "returnInput": {
        "orderId": "gid://shopify/Order/625362839",
        "returnLineItems": [
          {
            "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
            "quantity": 1,
            "returnReason": "SIZE_TOO_SMALL"
          }
        ]
      }
    }
  }'
  ```

  #### React Router

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

  export const loader = async ({request}) => {
    const { admin } = await authenticate.admin(request);
    const response = await admin.graphql(
      `#graphql
    mutation ReturnCreate($returnInput: ReturnInput!) {
      returnCreate(returnInput: $returnInput) {
        userErrors {
          field
          message
        }
        return {
          id
          order {
            id
          }
        }
      }
    }`,
    {
      variables: {
          "returnInput": {
              "orderId": "gid://shopify/Order/625362839",
              "returnLineItems": [
                  {
                      "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
                      "quantity": 1,
                      "returnReason": "SIZE_TOO_SMALL"
                  }
              ]
          }
      },
    },
    );
    const json = await response.json();
    return json.data;
  }
  ```

  #### Ruby

  ```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 ReturnCreate($returnInput: ReturnInput!) {
      returnCreate(returnInput: $returnInput) {
        userErrors {
          field
          message
        }
        return {
          id
          order {
            id
          }
        }
      }
    }
  QUERY

  variables = {
    "returnInput": {
      "orderId": "gid://shopify/Order/625362839",
      "returnLineItems": [
        {
          "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
          "quantity": 1,
          "returnReason": "SIZE_TOO_SMALL"
        }
      ]
    }
  }

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

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: {
      "query": `mutation ReturnCreate($returnInput: ReturnInput!) {
        returnCreate(returnInput: $returnInput) {
          userErrors {
            field
            message
          }
          return {
            id
            order {
              id
            }
          }
        }
      }`,
      "variables": {
          "returnInput": {
              "orderId": "gid://shopify/Order/625362839",
              "returnLineItems": [
                  {
                      "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
                      "quantity": 1,
                      "returnReason": "SIZE_TOO_SMALL"
                  }
              ]
          }
      },
    },
  });
  ```

  #### Response

  ```json
  {
    "returnCreate": {
      "userErrors": [],
      "return": {
        "id": "gid://shopify/Return/963805073",
        "order": {
          "id": "gid://shopify/Order/625362839"
        }
      }
    }
  }
  ```

* ### Create a return with a custom return reason note

  #### Description

  Create a return for a fulfilled \[line item]\(https\://shopify.dev/docs/api/admin-graphql/latest/objects/LineItem) with a note that explains the reason for the return. The example returns the created return's ID and the return reason note. Learn more about \[building for return management]\(https\://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management).

  #### Query

  ```graphql
  mutation ReturnCreateWithNote($returnInput: ReturnInput!) {
    returnCreate(returnInput: $returnInput) {
      userErrors {
        field
        message
      }
      return {
        id
        returnLineItems(first: 1) {
          edges {
            node {
              returnReasonNote
            }
          }
        }
      }
    }
  }
  ```

  #### Variables

  ```json
  {
    "returnInput": {
      "orderId": "gid://shopify/Order/625362839",
      "returnLineItems": [
        {
          "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
          "quantity": 1,
          "returnReason": "OTHER",
          "returnReasonNote": "Customer changed mind"
        }
      ]
    }
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "mutation ReturnCreateWithNote($returnInput: ReturnInput!) { returnCreate(returnInput: $returnInput) { userErrors { field message } return { id returnLineItems(first: 1) { edges { node { returnReasonNote } } } } } }",
   "variables": {
      "returnInput": {
        "orderId": "gid://shopify/Order/625362839",
        "returnLineItems": [
          {
            "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
            "quantity": 1,
            "returnReason": "OTHER",
            "returnReasonNote": "Customer changed mind"
          }
        ]
      }
    }
  }'
  ```

  #### React Router

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

  export const loader = async ({request}) => {
    const { admin } = await authenticate.admin(request);
    const response = await admin.graphql(
      `#graphql
    mutation ReturnCreateWithNote($returnInput: ReturnInput!) {
      returnCreate(returnInput: $returnInput) {
        userErrors {
          field
          message
        }
        return {
          id
          returnLineItems(first: 1) {
            edges {
              node {
                returnReasonNote
              }
            }
          }
        }
      }
    }`,
    {
      variables: {
          "returnInput": {
              "orderId": "gid://shopify/Order/625362839",
              "returnLineItems": [
                  {
                      "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
                      "quantity": 1,
                      "returnReason": "OTHER",
                      "returnReasonNote": "Customer changed mind"
                  }
              ]
          }
      },
    },
    );
    const json = await response.json();
    return json.data;
  }
  ```

  #### Ruby

  ```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 ReturnCreateWithNote($returnInput: ReturnInput!) {
      returnCreate(returnInput: $returnInput) {
        userErrors {
          field
          message
        }
        return {
          id
          returnLineItems(first: 1) {
            edges {
              node {
                returnReasonNote
              }
            }
          }
        }
      }
    }
  QUERY

  variables = {
    "returnInput": {
      "orderId": "gid://shopify/Order/625362839",
      "returnLineItems": [
        {
          "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
          "quantity": 1,
          "returnReason": "OTHER",
          "returnReasonNote": "Customer changed mind"
        }
      ]
    }
  }

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

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: {
      "query": `mutation ReturnCreateWithNote($returnInput: ReturnInput!) {
        returnCreate(returnInput: $returnInput) {
          userErrors {
            field
            message
          }
          return {
            id
            returnLineItems(first: 1) {
              edges {
                node {
                  returnReasonNote
                }
              }
            }
          }
        }
      }`,
      "variables": {
          "returnInput": {
              "orderId": "gid://shopify/Order/625362839",
              "returnLineItems": [
                  {
                      "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
                      "quantity": 1,
                      "returnReason": "OTHER",
                      "returnReasonNote": "Customer changed mind"
                  }
              ]
          }
      },
    },
  });
  ```

  #### Response

  ```json
  {
    "returnCreate": {
      "userErrors": [],
      "return": {
        "id": "gid://shopify/Return/963805074",
        "returnLineItems": {
          "edges": [
            {
              "node": {
                "returnReasonNote": "Customer changed mind"
              }
            }
          ]
        }
      }
    }
  }
  ```

* ### returnCreate reference

[Open in GraphiQL](http://localhost:3457/graphiql?query=mutation%20ReturnCreate\(%24returnInput%3A%20ReturnInput!\)%20%7B%0A%20%20returnCreate\(returnInput%3A%20%24returnInput\)%20%7B%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%20%20return%20%7B%0A%20%20%20%20%20%20id%0A%20%20%20%20%20%20order%20%7B%0A%20%20%20%20%20%20%20%20id%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D\&variables=%7B%0A%20%20%22returnInput%22%3A%20%7B%0A%20%20%20%20%22orderId%22%3A%20%22gid%3A%2F%2Fshopify%2FOrder%2F625362839%22%2C%0A%20%20%20%20%22returnLineItems%22%3A%20%5B%0A%20%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%22fulfillmentLineItemId%22%3A%20%22gid%3A%2F%2Fshopify%2FFulfillmentLineItem%2F820022594%22%2C%0A%20%20%20%20%20%20%20%20%22quantity%22%3A%201%2C%0A%20%20%20%20%20%20%20%20%22returnReason%22%3A%20%22SIZE_TOO_SMALL%22%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%5D%0A%20%20%7D%0A%7D)

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


export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation ReturnCreate($returnInput: ReturnInput!) {
    returnCreate(returnInput: $returnInput) {
      userErrors {
        field
        message
      }
      return {
        id
        order {
          id
        }
      }
    }
  }`,
  {
    variables: {
        "returnInput": {
            "orderId": "gid://shopify/Order/625362839",
            "returnLineItems": [
                {
                    "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
                    "quantity": 1,
                    "returnReason": "SIZE_TOO_SMALL"
                }
            ]
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}
```

## Input variables

JSON

```json
{
  "returnInput": {
    "orderId": "gid://shopify/Order/625362839",
    "returnLineItems": [
      {
        "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",
        "quantity": 1,
        "returnReason": "SIZE_TOO_SMALL"
      }
    ]
  }
}
```

## Response

JSON

```json
{
  "returnCreate": {
    "userErrors": [],
    "return": {
      "id": "gid://shopify/Return/963805073",
      "order": {
        "id": "gid://shopify/Order/625362839"
      }
    }
  }
}
```