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:
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
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:
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
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:
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
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:
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
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 bereturn_reason
.deleted
: A boolean value indicating whether the return reason was deleted.
View an Order’s Returns
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:
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
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:
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
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
A received return can’t be canceled.
You can cancel a return by sending a request to the Cancel Return API Route:
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
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.