How to Manage Returns

In this document, you’ll learn how to manage returns using the admin REST APIs.

Overview

Using the returns, orders, and return reasons admin REST APIs, you can manage returns and perform other related functionalities.

Scenario

You want to add or use the following admin functionalities:

• Manage Return Reasons. This includes listing return reasons, creating, updating, and deleting them.
• View an Order’s, Swap’s, and Claim’s Returns
• Mark a Return Received
• Cancel a Return

---

Prerequisites

Medusa Components

It is assumed that you already have a Medusa backend installed and set up. If not, you can follow our quickstart guide to get started.

JS Client

This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.

If you follow the JS Client code blocks, it’s assumed you already have Medusa’s JS Client installed and have created an instance of the client.

Medusa React

This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.

If you follow the Medusa React code blocks, it's assumed you already have Medusa React installed and have used MedusaProvider higher in your component tree.

Authenticated Admin User

You must be an authenticated admin user before following along with the steps in the tutorial.

You can learn more about authenticating as an admin user in the API reference.

---

Manage Return Reasons

Return reasons allow you to specify why an item is returned. They are especially useful for claims, but you can also use them to ask customers to specify the reason they’re requesting to return an item.

List Return Reasons

You can list available return reasons using the List Return Reasons API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.returnReasons.list()
.then(({ return_reasons }) => {
  console.log(return_reasons.length)
})

import { useAdminReturnReasons } from "medusa-react"

const ReturnReasons = () => {
  const { return_reasons, isLoading } = useAdminReturnReasons()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {return_reasons && !return_reasons.length && (
        <span>No Return Reasons</span>
      )}
      {return_reasons && return_reasons.length > 0 && (
        <ul>
          {return_reasons.map((reason) => (
            <li key={reason.id}>
              {reason.label}: {reason.value}
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default ReturnReasons

fetch(`<BACKEND_URL>/admin/return-reasons`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ return_reasons }) => {
  console.log(return_reasons.length)
})

curl -L -X GET '<BACKEND_URL>/admin/return-reasons' \
-H 'x-medusa-access-token: <API_TOKEN>'

This API Route doesn't require or accept any path or query parameters.

The request returns an array of return reason objects.

Create a Return Reason

You can create a return reason using the Create Return Reason API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.returnReasons.create({
  label: "Damaged",
  value: "damaged",
})
.then(({ return_reason }) => {
  console.log(return_reason.id)
})

import { useAdminCreateReturnReason } from "medusa-react"

const CreateReturnReason = () => {
  const createReturnReason = useAdminCreateReturnReason()
  // ...

  const handleCreate = (
    label: string,
    value: string
  ) => {
    createReturnReason.mutate({
      label,
      value,
    }, {
      onSuccess: ({ return_reason }) => {
        console.log(return_reason.id)
      }
    })
  }

  // ...
}

export default CreateReturnReason

fetch(`<BACKEND_URL>/admin/return-reasons`, {
  credentials: "include",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Damaged",
    value: "damaged",
  }),
})
.then((response) => response.json())
.then(({ return_reason }) => {
  console.log(return_reason.id)
})

curl -L -X POST '<BACKEND_URL>/admin/return-reasons' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
  "label": "Damaged",
  "value": "damaged"
}'

This API Route requires the following request body parameters:

• label: a string that will be used as the label of the return reason. This is typically the label shown to the customer or the merchant.
• value: a string that is unique among return reasons. It is typically used internally for identification

You can also pass other optional request body parameters, such as a description parameter or a parent_return_reason_id if this return reason is a child of another. You can learn more about available optional request body parameters in the API reference.

This request returns the created return reason as an object.

Update a Return Reason

You can update a return reason by sending a request to the Update Return Reason API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.returnReasons.update(returnReasonId, {
  label: "Damaged",
})
.then(({ return_reason }) => {
  console.log(return_reason.id)
})

import { useAdminUpdateReturnReason } from "medusa-react"

type Props = {
  returnReasonId: string
}

const ReturnReason = ({ returnReasonId }: Props) => {
  const updateReturnReason = useAdminUpdateReturnReason(
    returnReasonId
  )
  // ...

  const handleUpdate = (
    label: string
  ) => {
    updateReturnReason.mutate({
      label,
    }, {
      onSuccess: ({ return_reason }) => {
        console.log(return_reason.label)
      }
    })
  }

  // ...
}

export default ReturnReason

fetch(`<BACKEND_URL>/admin/return-reasons/${returnReasonId}`, {
  credentials: "include",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Damaged",
  }),
})
.then((response) => response.json())
.then(({ return_reason }) => {
  console.log(return_reason.id)
})

curl -L -X POST '<BACKEND_URL>/admin/return-reasons/<REASON_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
  "label": "Damaged"
}'

This API Route requires the return reason ID to be passed as a path parameter.

In the request body, you can pass any of the return reason’s fields that you want to update as parameters. In the example above, the label is passed in the request body to be updated.

The request returns the updated return reason as an object.

Delete a Return Reason

You can delete a return reason by sending a request to the Delete Return Reason API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.returnReasons.delete(returnReasonId)
.then(({ id, object, deleted }) => {
  console.log(id)
})

import { useAdminDeleteReturnReason } from "medusa-react"

type Props = {
  returnReasonId: string
}

const ReturnReason = ({ returnReasonId }: Props) => {
  const deleteReturnReason = useAdminDeleteReturnReason(
    returnReasonId
  )
  // ...

  const handleDelete = () => {
    deleteReturnReason.mutate(void 0, {
      onSuccess: ({ id, object, deleted }) => {
        console.log(id)
      }
    })
  }

  // ...
}

export default ReturnReason

fetch(`<BACKEND_URL>/admin/return-reasons/${returnReasonId}`, {
  credentials: "include",
  method: "DELETE",
})
.then((response) => response.json())
.then(({ id, object, deleted }) => {
  console.log(id)
})

curl -L -X DELETE '<BACKEND_URL>/admin/return-reasons/<REASON_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>'

This API Route requires the return reason ID as a path parameter.

The request returns the following fields:

• id: The ID of the deleted return reason.
• object: The type of object that was deleted. In this case, the value will be return_reason.
• deleted: A boolean value indicating whether the return reason was deleted.

---

View an Order’s Returns

Note

You can view all returns in your commerce system, regardless of which order they belong to, using the List Returns API Route.

When you retrieve an order using the Get Order API Route, you can access the returns within the order object:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.orders.retrieve(orderId)
.then(({ order }) => {
  console.log(order.returns)
})

import { useAdminOrder } from "medusa-react"

const Order = () => {
  const { 
    order, 
    isLoading, 
  } = useAdminOrder(orderId)

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {order && (
        <>
          <span>{order.display_id}</span>
          {order.returns?.length > 0 && (
            <ul>
              {order.returns.map((orderReturn) => (
                <li key={orderReturn.id}>{orderReturn.id}</li>
              ))}
            </ul>
          )}
        </>
      )}
      
    </div>
  )
}

export default Order

fetch(`<BACKEND_URL>/admin/orders/${orderId}`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ order }) => {
  console.log(order.returns)
})

curl -L -X GET '<BACKEND_URL>/admin/orders/<ORDER_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>'

This API Route requires the order ID as a path parameter.

The request returns the order as an object. In that object, you can access an array of return objects using the property returns of the order object.

---

View a Swap’s Return

You can retrieve a swap either using the Get Order API Route as explained here, or using the List Swaps or Get Swap API Routes.

In a swap object, the swap’s return is available under the return_order property.

---

View a Claim’s Return

You can retrieve a claim using the Get Order API Route as explained here. In a claim object, the claim’s return is available under the return_order property.

---

Mark a Return as Received

You can mark a return as received by sending a request to the Receive a Return API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.returns.receive(return_id, {
  items: [
    {
      item_id,
      quantity: 1,
    },
  ],
})
.then((data) => {
  console.log(data.return.id)
})

import { useAdminReceiveReturn } from "medusa-react"

type ReceiveReturnData = {
  items: {
    item_id: string
    quantity: number
  }[]
}

type Props = {
  returnId: string
}

const Return = ({ returnId }: Props) => {
  const receiveReturn = useAdminReceiveReturn(
    returnId
  )
  // ...

  const handleReceive = (data: ReceiveReturnData) => {
    receiveReturn.mutate(data, {
      onSuccess: ({ return: dataReturn }) => {
        console.log(dataReturn.status)
      }
    })
  }

  // ...
}

export default Return

fetch(`<BACKEND_URL>/admin/returns/${returnId}/receive`, {
  credentials: "include",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      {
        item_id,
        quantity: 1,
      },
    ],
  }),
})
.then((response) => response.json())
.then((data) => {
  console.log(data.return.id)
})

curl -L -X POST '<BACKEND_URL>/admin/returns/<RETURN_ID>/receive' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "items": [
      {
        "item_id": "<ITEM_ID>",
        "quantity": 1
      }
    ]
}'

This API Route requires the ID of the return as a path parameter.

In the request body, the items parameter is required. It’s an array of objects having the following properties:

• item_id: a string indicating the ID of the line item in the order that is received.
• quantity: a number indicating the quantity of the line item that was received.

By default, the refund amount specified in the return will be refunded. If you want to refund a custom amount, you can pass the optional request body parameter refund, with its value being a number indicating the amount to refund. The amount must be less than the order’s refundable_amount.

The request returns the updated return as an object.

---

Cancel a Return

Note

A received return can’t be canceled.

You can cancel a return by sending a request to the Cancel Return API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.returns.cancel(returnId)
.then(({ order }) => {
  console.log(order.returns)
})

import { useAdminCancelReturn } from "medusa-react"

type Props = {
  returnId: string
}

const Return = ({ returnId }: Props) => {
  const cancelReturn = useAdminCancelReturn(
    returnId
  )
  // ...

  const handleCancel = () => {
    cancelReturn.mutate(void 0, {
      onSuccess: ({ order }) => {
        console.log(order.returns)
      }
    })
  }

  // ...
}

export default Return

fetch(`<BACKEND_URL>/admin/returns/${returnId}/cancel`, {
  credentials: "include",
  method: "POST",
})
.then((response) => response.json())
.then(({ order }) => {
  console.log(order.returns)
})

curl -L -X POST '<BACKEND_URL>/admin/returns/<RETURN_ID>/cancel' \
-H 'x-medusa-access-token: <API_TOKEN>'

This API Route requires the return ID to be passed as a path parameter.

The request returns one of the following object types:

• If a return belongs to a swap, a swap object is returned. You can access the returns in the return_order property of the swap object.
• If a return belongs to a claim, a claim object is returned. You can access the returns in the return_order property of the claim object.
• Otherwise, an order object is returned. You can access the returns in the returns property of the order object.

---

See Also

• How to manage orders using the REST APIs
• How to manage swaps using the REST APIs
• How to manage claims using the REST APIs