Choose a version:

returnCreate

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 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 or declining 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, and enables you to create a reverse delivery 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 query to retrieve the return by its ID. Learn more about providing a return management workflow for merchants.

Arguments

Anchor to returnInputreturnInput •ReturnInput! required: Specifies the input fields for a return.

Was this section helpful?

Anchor to ReturnCreatePayload returnsReturnCreatePayload returns

Anchor to returnreturn •Return: The created return.
Anchor to userErrorsuserErrors •[ReturnUserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

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

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2024-10/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"
        }
      ]
    }
  }
}'

Remix

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 data = await response.json();

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

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

{
  "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

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2024-10/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"
        }
      ]
    }
  }
}'

Remix

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 data = await response.json();

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

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

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

returnCreate reference

Examples

Open in GraphiQL

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

mutation ReturnCreate($returnInput: ReturnInput!) {

returnCreate(returnInput: $returnInput) {

userErrors {

field

message

}

return {

order {

}

}`,

{

variables: {

"returnInput": {

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

"returnLineItems": [

{

"fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/820022594",

"quantity": 1,

"returnReason": "SIZE_TOO_SMALL"

}

]

}

);

const data = await response.json();

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

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2024-10/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"
        }
      ]
    }
  }
}'

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 data = await response.json();

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"
          }
        ]
      }
    },
  },
});

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)

Input variables

JSON

{

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

}