How to Create a Return in the Storefront

In this document, you’ll learn how to implement a create return flow in the storefront.

Overview

Customers may need to return items they received from an order they placed for different reasons, such as ordering an incorrect size of the item.

The Medusa backend allows automating the process of returning an item by providing the necessary mechanism that allows customers to create the return request themselves. This guide illustrates how you can implement that mechanism in your storefront.

The process of creating a return is as follows:

• Ask the customer to select the items they want to return. You can also allow customers to select the return shipping option to use to return the item.
• Create the return in the Medusa backend.

Note

Refunding the customer is handled by admins. You can learn how to implement or use this functionality in the Manage Returns guide.

---

Prerequisites

Medusa Components

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

It's also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install the Next.js Starter Template.

JS Client

This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client and JavaScript’s Fetch API.

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.

---

Step 1: Collecting Return Details

When a customer wants to create a return, they must choose the items they want to return. To display the items in the order, you can retrieve the order as explained in this guide. You can then display the items in an order using order.items, which is an array of items.

Showing Return Shipping Options

You can optionally allow customers to choose a return shipping option that they’ll use to return the items. To show the customers the available return shipping options, send a request to the Get Shipping Options API Route:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.shippingOptions.list({
  is_return: "true",
})
.then(({ shipping_options }) => {
  console.log(shipping_options.length)
})

import { useShippingOptions } from "medusa-react"

const ReturnShippingOptions = () => {
  const { 
    shipping_options, 
    isLoading, 
  } = useShippingOptions({
    is_return: "true",
  })

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {shipping_options?.length && 
        shipping_options?.length > 0 && (
        <ul>
          {shipping_options?.map((shipping_option) => (
            <li key={shipping_option.id}>
              {shipping_option.id}
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default ReturnShippingOptions

fetch(`<BACKEND_URL>/store/shipping-options?is_return=true`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ shipping_options }) => {
  console.log(shipping_options.length)
})

This API Route allows you to pass the is_return query parameter to indicate whether the shipping options should be return shipping options. You can learn about other available filters in the API reference.

The request returns an array of shipping option objects.

---

Step 2: Create Return

You can create the return by sending a request to the Create Return API Route:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.returns.create({
  order_id,
  items: [
    {
      item_id,
      quantity: 1,
    },
  ],
  return_shipping: {
    option_id,
  },
})
.then((data) => {
  console.log(data.return.id)
})

import { useCreateReturn } from "medusa-react"

type CreateReturnData = {
  items: {
    item_id: string,
    quantity: number
  }[]
  return_shipping: {
    option_id: string
  }
}

type Props = {
  orderId: string
}

const CreateReturn = ({ orderId }: Props) => {
  const createReturn = useCreateReturn()
  // ...

  const handleCreate = (data: CreateReturnData) => {
    createReturn.mutate({
      ...data,
      order_id: orderId
    }, {
      onSuccess: ({ return: returnData }) => {
        console.log(returnData.id)
      }
    })
  }

  // ...
}

export default CreateReturn

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

This API Route requires the following request body parameters:

• order_id: a string indicating the ID of the order to create the return for.
• items: an array of objects, each object being an item from the order to return. Each object must have the following properties:
  • item_id: a string indicating the ID of the item in the order.
  • quantity: a number indicating the quantity to return.

You can optionally pass the return_shipping parameter, which is the return shipping option that the customer will use to return the item. It’s an object that has a required property option_id, which is a string indicating the ID of the return shipping option.

The request returns the created return as an object.

---

See Also

• How to manage returns as an admin
• How to implement a create swap flow in a storefront