---
description: "Learn how to manage returns using the admin REST APIs. This guide includes how to manage return reasons, view returns, mark a return as received, and cancel a return."
addHowToData: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# 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](../../../development/backend/install.mdx) 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](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration).

### 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](../../../medusa-react/overview.mdx) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.mdx#usage).

### 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](https://docs.medusajs.com/api/admin#authentication).

---

## 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](https://docs.medusajs.com/api/admin#return-reasons_getreturnreasons):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

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

  </TabItem>
  <TabItem value="medusa-react" label="Medusa React">

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

  </TabItem>
  <TabItem value="fetch" label="Fetch API">

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

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X GET '<BACKEND_URL>/admin/return-reasons' \
    -H 'Authorization: Bearer <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

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](https://docs.medusajs.com/api/admin#return-reasons_postreturnreasons):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

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

  </TabItem>
  <TabItem value="medusa-react" label="Medusa React">

    ```tsx
    import { useAdminCreateReturnReason } from "medusa-react"

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

      const handleCreate = () => {
        createReturnReason.mutate({
          label: "Damaged",
          value: "damaged",
        })
      }

      // ...
    }

    export default CreateReturnReason
    ```

  </TabItem>
  <TabItem value="fetch" label="Fetch API">

    ```ts
    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)
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X POST '<BACKEND_URL>/admin/return-reasons' \
    -H 'Authorization: Bearer <API_TOKEN>' \
    -H 'Content-Type: application/json' \
    --data-raw '{
      "label": "Damaged",
      "value": "damaged"
    }'
    ```

  </TabItem>
</Tabs>

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](https://docs.medusajs.com/api/admin#return-reasons_postreturnreasons).

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](https://docs.medusajs.com/api/admin#return-reasons_postreturnreasonsreason):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

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

  </TabItem>
  <TabItem value="medusa-react" label="Medusa React">

    ```tsx
    import { useAdminUpdateReturnReason } from "medusa-react"

    const UpdateReturnReason = () => {
      const updateReturnReason = useAdminUpdateReturnReason(
        returnReasonId
      )
      // ...

      const handleUpdate = () => {
        updateReturnReason.mutate({
          label: "Damaged",
        })
      }

      // ...
    }

    export default UpdateReturnReason
    ```

  </TabItem>
  <TabItem value="fetch" label="Fetch API">

    ```ts
    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)
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X POST '<BACKEND_URL>/admin/return-reasons/<REASON_ID>' \
    -H 'Authorization: Bearer <API_TOKEN>' \
    -H 'Content-Type: application/json' \
    --data-raw '{
      "label": "Damaged"
    }'
    ```

  </TabItem>
</Tabs>

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](https://docs.medusajs.com/api/admin#return-reasons_deletereturnreason):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

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

  </TabItem>
  <TabItem value="medusa-react" label="Medusa React">

    ```tsx
    import { useAdminDeleteReturnReason } from "medusa-react"

    const DeleteReturnReason = () => {
      const deleteReturnReason = useAdminDeleteReturnReason(
        returnReasonId
      )
      // ...

      const handleDelete = () => {
        deleteReturnReason.mutate()
      }

      // ...
    }

    export default DeleteReturnReason
    ```

  </TabItem>
  <TabItem value="fetch" label="Fetch API">

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

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X DELETE '<BACKEND_URL>/admin/return-reasons/<REASON_ID>' \
    -H 'Authorization: Bearer <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

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](https://docs.medusajs.com/api/admin#return-reasons_getreturnreasons).

:::

When you retrieve an order using the [Get Order API Route](https://docs.medusajs.com/api/admin#orders_getordersorder), you can access the returns within the order object:

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

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

  </TabItem>
  <TabItem value="medusa-react" label="Medusa React">

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

  </TabItem>
  <TabItem value="fetch" label="Fetch API">

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

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X GET '<BACKEND_URL>/admin/orders/<ORDER_ID>' \
    -H 'Authorization: Bearer <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

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](./manage-swaps.mdx#view-orders-swaps), or using the [List Swaps](https://docs.medusajs.com/api/admin#swaps_getswaps) or [Get Swap](https://docs.medusajs.com/api/admin#swaps_getswapsswap) 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](./manage-claims#view-orders-claims). 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](https://docs.medusajs.com/api/admin#returns_postreturnsreturnreceive):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

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

  </TabItem>
  <TabItem value="medusa-react" label="Medusa React">

    ```tsx
    import { useAdminReceiveReturn } from "medusa-react"

    const ReceiveReturn = () => {
      const receiveReturn = useAdminReceiveReturn(
        returnId
      )
      // ...

      const handleReceive = () => {
        receiveReturn.mutate({
          email,
        })
      }

      // ...
    }

    export default ReceiveReturn
    ```

  </TabItem>
  <TabItem value="fetch" label="Fetch API">

    ```ts
    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)
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

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

  </TabItem>
</Tabs>

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](https://docs.medusajs.com/api/admin#returns_postreturnsreturncancel):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

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

  </TabItem>
  <TabItem value="medusa-react" label="Medusa React">

    ```tsx
    import { useAdminCancelReturn } from "medusa-react"

    const CancelReturn = () => {
      const cancelReturn = useAdminCancelReturn(
        returnId
      )
      // ...

      const handleCancel = () => {
        cancelReturn.mutate()
      }

      // ...
    }

    export default CancelReturn
    ```

  </TabItem>
  <TabItem value="fetch" label="Fetch API">

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

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X POST '<BACKEND_URL>/admin/returns/<RETURN_ID>/cancel' \
    -H 'Authorization: Bearer <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

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](./manage-orders.mdx)
- [How to manage swaps using the REST APIs](./manage-swaps.mdx)
- [How to manage claims using the REST APIs](./manage-claims.mdx)
