From ceeba5fba624050e805fae9ad6f0c0214f2ef66c Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 27 Apr 2023 12:27:55 +0300 Subject: [PATCH] docs: added how to manage swaps documentation (#3941) * docs: added how to manage swaps documentation * added a note about listing swaps * fix console.log --- .../modules/orders/admin/manage-orders.mdx | 2 +- .../modules/orders/admin/manage-swaps.mdx | 536 ++++++++++++++++++ docs/content/modules/orders/overview.mdx | 3 +- .../api/routes/admin/orders/fulfill-swap.ts | 4 +- www/docs/sidebars.js | 7 +- 5 files changed, 543 insertions(+), 9 deletions(-) create mode 100644 docs/content/modules/orders/admin/manage-swaps.mdx diff --git a/docs/content/modules/orders/admin/manage-orders.mdx b/docs/content/modules/orders/admin/manage-orders.mdx index 260a804d7b..8906528ec8 100644 --- a/docs/content/modules/orders/admin/manage-orders.mdx +++ b/docs/content/modules/orders/admin/manage-orders.mdx @@ -1,5 +1,5 @@ --- -description: 'Learn how to implement order-editing features for admins using the REST APIs. This guide includes how to create an order edit and move order edit to request state, and more.' +description: 'Learn how to manage orders using the admin REST APIs. This guide includes how to list and filter orders, manage their payment and fulfillment, and more.' addHowToData: true --- diff --git a/docs/content/modules/orders/admin/manage-swaps.mdx b/docs/content/modules/orders/admin/manage-swaps.mdx new file mode 100644 index 0000000000..0749a4fea0 --- /dev/null +++ b/docs/content/modules/orders/admin/manage-swaps.mdx @@ -0,0 +1,536 @@ +--- +description: "Learn how to manage swaps using the admin REST APIs. This guide includes how to view an order's swaps, manage a swap's payment and fulfillment, and cancel a swap." +addHowToData: true +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# How to Manage Swaps + +In this document, you’ll learn how to manage swaps using the admin REST APIs. + +## Overview + +Using the order’s admin REST APIs, you can manage and process the swaps of an order in your commerce store. + +### Scenario + +You want to add or use the following admin functionalities: + +- View an order’s swaps. +- Process a swap’s payment. +- Manage a swap’s fulfillment. This includes creating a fulfillment, creating a shipment, and canceling a fulfillment. +- Cancel a swap. + +--- + +## 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). + +--- + +## View Order’s Swaps + +:::note + +If you want to view all swaps in your system, and not swaps specific to an order, you can use the [List Swaps endpoint](/api/admin#tag/Swaps/operation/GetSwaps) instead. + +::: + +You can view an order’s swaps by retrieving the order using the [Get Order endpoint](/api/admin#tag/Orders/operation/GetOrdersOrder): + + + + +```ts +medusa.admin.orders.retrieve(orderId) +.then(({ order }) => { + console.log(order.swaps) +}) +``` + + + + +```tsx +import { useAdminOrder } from "medusa-react" + +const Order = () => { + const { + order, + isLoading, + } = useAdminOrder(orderId) + + return ( +
+ {isLoading && Loading...} + {order && ( + <> + {order.display_id} + {order.swaps?.length > 0 && ( +
    + {order.swaps.map((swap) => ( +
  • {swap.difference_due}
    • + ))} +
+ )} + + )} +
+ ) +} + +export default Order +``` + + + + +```ts +fetch(`/admin/orders/${orderId}`, { + credentials: "include", +}) +.then((response) => response.json()) +.then(({ order }) => { + console.log(order.swaps) +}) +``` + + + + +```bash +curl -L -X GET '/admin/orders/' \ +-H 'Authorization: Bearer ' +``` + + + + +This endpoint requires the order ID to be passed as a path parameter. + +The request returns the order as an object. The order’s swaps are available under the `swaps` property, which is an array of swap objects. + +--- + +## Process Swap Payment + +Processing a swap’s payment can mean either refunding or capturing payment, depending on the value of `difference_due` of the swap. If the `difference_due` is less than 0, then the payment should be refunded. If it’s greater than 0, then the payment should be captured. If it’s 0, no payment processing is performed. + +Regardless of whether you need to refund or capture the payment, you can process the swap’s payment by sending a request to the [Process Swap Payment endpoint](/api/admin#tag/Orders/operation/PostOrdersOrderSwapsSwapProcessPayment): + + + + +```ts +medusa.admin.orders.processSwapPayment(orderId, swapId) +.then(({ order }) => { + console.log(order.swaps) +}) +``` + + + + +```tsx +import { useAdminProcessSwapPayment } from "medusa-react" + +const ProcessPayment = () => { + const processPayment = useAdminProcessSwapPayment( + orderId + ) + // ... + + const handleProcess = () => { + processPayment.mutate(swapId) + } + + // ... +} + +export default ProcessPayment +``` + + + + + + +```ts +fetch(`/admin/orders/${orderId}/swaps/${swapId}/process-payment`, { + credentials: "include", + method: "POST", +}) +.then((response) => response.json()) +.then(({ order }) => { + console.log(order.swaps) +}) +``` + + + + +```bash +curl -L -X POST '/admin/orders//swaps//process-payment' \ +-H 'Authorization: Bearer ' +``` + + + + +This endpoint requires the order ID and the swap ID as path parameters. + +The request returns the updated order as an object. You can access the swaps of the order in the `order.swaps` property. It’s an array of swap objects. + +--- + +## Manage a Swap’s Fulfillments + +### View Swap’s Fulfillments + +Fulfillments are available on a swap object under the `fulfillments` property, which is an array of fulfillment objects. + +### Create a Fulfillment + +You can create a fulfillment for a swap by sending a request to the [Create Swap Fulfillment endpoint](/api/admin#tag/Orders/operation/PostOrdersOrderSwapsSwapFulfillments): + + + + +```ts +medusa.admin.orders.fulfillSwap(orderId, swapId, { +}) +.then(({ order }) => { + console.log(order.swaps) +}) +``` + + + + +```tsx +import { useAdminFulfillSwap } from "medusa-react" + +const FulfillSwap = () => { + const fulfillSwap = useAdminFulfillSwap( + orderId + ) + // ... + + const handleFulfill = () => { + fulfillSwap.mutate({ + swap_id: swapId, + }) + } + + // ... +} + +export default FulfillSwap +``` + + + + + + +```ts +fetch(`/admin/orders/${orderId}/swaps/${swapId}/fulfillments`, { + credentials: "include", + method: "POST", +}) +.then((response) => response.json()) +.then(({ order }) => { + console.log(order.swaps) +}) +``` + + + + +```bash +curl -L -X POST '/admin/orders//swaps//fulfillments' \ +-H 'Authorization: Bearer ' +``` + + + + +This endpoint requires the order ID and swap ID as path parameters. + +In the request body, you can pass optional parameters such as `metadata` or `no_notification`. These parameters will be used to create the fulfillment. You can learn more about available request body parameters in the [API reference](/api/admin#tag/Orders/operation/PostOrdersOrderSwapsSwapFulfillments). + +The request returns the updated order as an object. You can access the order’s swaps in the `swaps` property, which is an array of swap objects. + +### Create a Shipment + +You can create a shipment for a swap’s fulfillment using the [Create Swap Shipment endpoint](/api/admin#tag/Orders/operation/PostOrdersOrderSwapsSwapShipments): + + + + +```ts +medusa.admin.orders.createSwapShipment(orderId, swapId, { + fulfillment_id, +}) +.then(({ order }) => { + console.log(order.swaps) +}) +``` + + + + +```tsx +import { useAdminCreateSwapShipment } from "medusa-react" + +const CreateShipment = () => { + const createShipment = useAdminCreateSwapShipment( + orderId + ) + // ... + + const handleCreate = () => { + createShipment.mutate({ + swap_id, + fulfillment_id, + }) + } + + // ... +} + +export default CreateShipment +``` + + + + + + +```ts +fetch(`/admin/orders/${orderId}/swaps/${swapId}/shipments`, { + credentials: "include", + method: "POST", + headers: { + "Content-Type": "application/json", + }, + body: JSON.stringify({ + fulfillment_id, + }), +}) +.then((response) => response.json()) +.then(({ order }) => { + console.log(order.swaps) +}) +``` + + + + +```bash +curl -L -X POST '/admin/orders//swaps//shipments' \ +-H 'Authorization: Bearer '\ +-H 'Content-Type: application/json' \ +--data-raw '{ + "fulfillment_id": "" +}' +``` + + + + +This endpoint expects the order and swap IDs to be passed as path parameters. + +In the request body, it’s required to pass the `fulfillment_id` parameter, which is the ID of the fulfillment the shipment is being created for. You can pass other optional parameters, such as an array of tracking numbers. You can learn more in the [API reference](/api/admin#tag/Orders/operation/PostOrdersOrderSwapsSwapShipments). + +The request returns the updated order as an object. As mentioned before, a swap’s fulfillments can be accessed using the `fulfillments` property of a swap object. You can access the shipments, known as tracking links, of a fulfillment using the `tracking_links` property of a fulfillment object. The value of `tracking_links` is an array of tracking link objects. + +You can alternatively access the tracking numbers using the `tracking_numbers` property of a fulfillment object, which is an array of strings. + +You can access the status of a swap’s fulfillment using the `fulfillment_status` property of a swap object. + +### Cancel a Fulfillment + +:::note + +You can’t cancel a fulfillment that has a shipment + +::: + +You can cancel a fulfillment by sending a request to the [Cancel Swap Fulfillment endpoint](/api/admin#tag/Orders/operation/PostOrdersSwapFulfillmentsCancel): + + + + +```ts +medusa.admin.orders.cancelSwapFulfillment( + orderId, + swapId, + fulfillmentId +) +.then(({ order }) => { + console.log(order.swaps) +}) +``` + + + + +```tsx +import { useAdminCancelSwapFulfillment } from "medusa-react" + +const CancelFulfillment = () => { + const cancelFulfillment = useAdminCancelSwapFulfillment( + orderId + ) + // ... + + const handleCancel = () => { + cancelFulfillment.mutate({ + swap_id, + fulfillment_id, + }) + } + + // ... +} + +export default CancelFulfillment +``` + + + + + + +```ts +fetch(`/admin/orders/${orderId}/swaps/${swapId}/shipments/${fulfillmentId}/cancel`, { + credentials: "include", + method: "POST", +}) +.then((response) => response.json()) +.then(({ order }) => { + console.log(order.swaps) +}) +``` + + + + +```bash +curl -L -X POST '/admin/orders//swaps//fulfillments//cancel' \ +-H 'Authorization: Bearer ' +``` + + + + +This endpoint requires the order, swap, and fulfillment IDs to be passed as path parameters. + +The request returns the updated order as an object. You can access the swaps using the `swaps` property of the order object, which is an array of swap objects. + +You can check the fulfillment status of a swap using the `fulfillment_status` property of the swap object. + +--- + +## Cancel Swap + +:::note + +You can’t cancel a swap that has been refunded. You must also cancel all swap’s fulfillments and return first. + +::: + +You can cancel a swap by sending a request to the [Cancel Swap endpoint](/api/admin#tag/Orders/operation/PostOrdersSwapCancel): + + + + +```ts +medusa.admin.orders.cancelSwap(orderId, swapId) +.then(({ order }) => { + console.log(order.swaps) +}) +``` + + + + +```tsx +import { useAdminCancelSwap } from "medusa-react" + +const CancelSwap = () => { + const cancelSwap = useAdminCancelSwap( + orderId + ) + // ... + + const handleCancel = () => { + cancelSwap.mutate(swapId) + } + + // ... +} + +export default CancelSwap +``` + + + + + + +```ts +fetch(`/admin/orders/${orderId}/swaps/${swapId}/cancel`, { + credentials: "include", + method: "POST", + }) + .then((response) => response.json()) + .then(({ order }) => { + console.log(order.swaps) + }) +``` + + + + +```bash +curl -L -X POST '/admin/orders//swaps//cancel' \ +-H 'Authorization: Bearer ' +``` + + + + +This endpoint requires the order and swap IDs as path parameters. + +The request returns the updated order as an object. You can access the swaps using the `swaps` property of the order object, which is an array of swap objects. + +--- + +## See Also + +- [How to manage orders using admin APIs](./manage-orders.mdx) diff --git a/docs/content/modules/orders/overview.mdx b/docs/content/modules/orders/overview.mdx index 0128697c16..3b4507a5b1 100644 --- a/docs/content/modules/orders/overview.mdx +++ b/docs/content/modules/orders/overview.mdx @@ -174,12 +174,11 @@ Customers can also request to return or swap items. This allows for implementing }, { type: 'link', - href: '#', + href: '/modules/orders/admin/manage-swaps', label: 'Admin: Manage Swaps', customProps: { icon: Icons['academic-cap-solid'], description: 'Learn how to manage swaps using Admin APIs.', - isSoon: true, } }, { diff --git a/packages/medusa/src/api/routes/admin/orders/fulfill-swap.ts b/packages/medusa/src/api/routes/admin/orders/fulfill-swap.ts index 970dbc3083..be7e50087a 100644 --- a/packages/medusa/src/api/routes/admin/orders/fulfill-swap.ts +++ b/packages/medusa/src/api/routes/admin/orders/fulfill-swap.ts @@ -37,7 +37,9 @@ import { updateInventoryAndReservations } from "./create-fulfillment" * import Medusa from "@medusajs/medusa-js" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token - * medusa.admin.orders.fulfillSwap(order_id, swap_id) + * medusa.admin.orders.fulfillSwap(order_id, swap_id, { + * + * }) * .then(({ order }) => { * console.log(order.id); * }); diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index 019e1ec9ea..b9a370f0be 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -774,12 +774,9 @@ module.exports = { label: "Admin: Edit an Order", }, { - type: "link", - href: "#", + type: "doc", + id: "modules/orders/admin/manage-swaps", label: "Admin: Manage Swaps", - customProps: { - sidebar_is_soon: true, - }, }, { type: "link",