docs: added manage returns documentation (#3943)

docs/content/modules/orders/admin/manage-returns.mdx

@@ -0,0 +1,651 @@
+---
+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.md) installed and have [created an instance of the client](../../../js-client/overview.md#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.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#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](/api/admin/#section/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 endpoint](/api/admin#tag/Return-Reasons/operation/GetReturnReasons):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<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 endpoint does not 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 endpoint](/api/admin#tag/Return-Reasons/operation/PostReturnReasons):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<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 endpoint 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](/api/admin#tag/Return-Reasons/operation/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 endpoint](/api/admin#tag/Return-Reasons/operation/PostReturnReasonsReason):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<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 endpoint 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 endpoint](/api/admin#tag/Return-Reasons/operation/DeleteReturnReason):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<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 endpoint 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 endpoint](/api/admin#tag/Returns/operation/GetReturns).
+
+:::
+
+When you retrieve an order using the [Get Order endpoint](/api/admin#tag/Orders/operation/GetOrdersOrder), you can access the returns within the order object:
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<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 endpoint 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 endpoint as explained here, or using the [List Swaps](/api/admin#tag/Swaps/operation/GetSwaps) or [Get Swap endpoint](/api/admin#tag/Swaps/operation/GetSwapsSwap).
+
+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 endpoint and accessing the `claims` property of the order object, which is an array of claim objects. 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 endpoint](/api/admin#tag/Returns/operation/PostReturnsReturnReceive):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<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 endpoint 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 endpoint](/api/admin#tag/Returns/operation/PostReturnsReturnCancel):
+
+<Tabs groupId="request-type" wrapperClassName="code-tabs">
+<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 endpoint 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.
+- If a return belongs to a claim, a claim object is returned.
+- Otherwise, an order object is returned.
+
+---
+
+## See Also
+
+- [How to manage orders using the REST APIs](./manage-orders.mdx)
+- [How to manage swaps using the REST APIs](./manage-returns.mdx)

docs/content/modules/orders/admin/manage-swaps.mdx

@@ -23,6 +23,12 @@ You want to add or use the following admin functionalities:
 - Manage a swap’s fulfillment. This includes creating a fulfillment, creating a shipment, and canceling a fulfillment.
 - Cancel a swap.
 
+:::note
+
+You can learn about managing returns in the [Manage Returns documentation](./manage-returns.mdx).
+
+:::
+
 ---
 
 ## Prerequisites
@@ -534,3 +540,4 @@ The request returns the updated order as an object. You can access the swaps usi
 ## See Also
 
 - [How to manage orders using admin APIs](./manage-orders.mdx)
+- [How to manage returns using admin APIs](./manage-returns.mdx)

docs/content/modules/orders/orders.md

@@ -296,6 +296,7 @@ The draft order’s ID is stored in the `draft_order_id` attribute. You can also
 
 ## See Also
 
+- [How to manage orders](./admin/manage-orders.mdx)
 - [How to edit an order](./admin/edit-order.mdx)
 - [How to handle order edits on the storefront](./storefront/handle-order-edits.mdx)
 - [How to Implement Claim Order Flow in the storefront](./storefront/implement-claim-order.mdx)

docs/content/modules/orders/overview.mdx

@@ -164,12 +164,11 @@ Customers can also request to return or swap items. This allows for implementing
 <DocCardList colSize={4} items={[
   {
     type: 'link',
-    href: '#',
+    href: '/modules/orders/admin/manage-returns',
     label: 'Admin: Manage Returns',
     customProps: {
       icon: Icons['academic-cap-solid'],
       description: 'Learn how to manage returns using Admin APIs.',
-      isSoon: true,
     }
   },
   {

docs/content/modules/orders/returns.md

@@ -133,6 +133,7 @@ You can access the shipping method by expanding the `shipping_method` relation a
 
 ## See Also
 
+- [How to manage returns](./admin/manage-returns.mdx)
 - [Orders architecture overview](./orders.md)
 - [Swaps architecture overview](./swaps.md)
 - [Claims architecture overview](./claims.md)

docs/content/modules/orders/swaps.md

@@ -171,4 +171,5 @@ You can access the swap’s shipping address ID using the `shipping_address_id`
 
 ## See Also
 
+- [How to manage swaps](./admin/manage-swaps.mdx)
 - [Order Architecture Overview](./orders.md)

www/docs/sidebars.js

@@ -779,12 +779,9 @@ module.exports = {
           label: "Admin: Manage Swaps",
         },
         {
-          type: "link",
-          href: "#",
+          type: "doc",
+          id: "modules/orders/admin/manage-returns",
           label: "Admin: Manage Returns",
-          customProps: {
-            sidebar_is_soon: true,
-          },
         },
         {
           type: "link",