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.

Note

You can learn about managing returns in the Manage Returns documentation.

---

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.

---

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 API Route instead.

You can view an order’s swaps by retrieving the order using the Get Order API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

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.swaps?.length > 0 && (
            <ul>
              {order.swaps.map((swap) => (
                <li key={swap.id}>{swap.difference_due}</li>
              ))}
            </ul>
          )}
        </>
      )}
    </div>
  )
}

export default Order

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

curl -L -X GET '<BACKEND_URL>/admin/orders/<ORDER_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>'

This API Route 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 API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.orders.processSwapPayment(orderId, swapId)
.then(({ order }) => {
  console.log(order.swaps)
})

import { useAdminProcessSwapPayment } from "medusa-react"

type Props = {
  orderId: string,
  swapId: string
}

const Swap = ({
  orderId,
  swapId
}: Props) => {
  const processPayment = useAdminProcessSwapPayment(
    orderId
  )
  // ...

  const handleProcessPayment = () => {
    processPayment.mutate(swapId, {
      onSuccess: ({ order }) => {
        console.log(order.swaps)
      }
    })
  }

  // ...
}

export default Swap

fetch(`<BACKEND_URL>/admin/orders/${orderId}/swaps/${swapId}/process-payment`, {
  credentials: "include",
  method: "POST",
})
.then((response) => response.json())
.then(({ order }) => {
  console.log(order.swaps)
})

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/swaps/<SWAP_ID>/process-payment' \
-H 'x-medusa-access-token: <API_TOKEN>'

This API Route 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 API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.orders.fulfillSwap(orderId, swapId, {
})
.then(({ order }) => {
  console.log(order.swaps)
})

import { useAdminFulfillSwap } from "medusa-react"

type Props = {
  orderId: string,
  swapId: string
}

const Swap = ({
  orderId,
  swapId
}: Props) => {
  const fulfillSwap = useAdminFulfillSwap(
    orderId
  )
  // ...

  const handleFulfill = () => {
    fulfillSwap.mutate({
      swap_id: swapId,
    }, {
      onSuccess: ({ order }) => {
        console.log(order.swaps)
      }
    })
  }

  // ...
}

export default Swap

fetch(`<BACKEND_URL>/admin/orders/${orderId}/swaps/${swapId}/fulfillments`, {
  credentials: "include",
  method: "POST",
})
.then((response) => response.json())
.then(({ order }) => {
  console.log(order.swaps)
})

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/swaps/<SWAP_ID>/fulfillments' \
-H 'x-medusa-access-token: <API_TOKEN>'

This API Route 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.

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 API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.orders.createSwapShipment(orderId, swapId, {
  fulfillment_id,
})
.then(({ order }) => {
  console.log(order.swaps)
})

import { useAdminCreateSwapShipment } from "medusa-react"

type Props = {
  orderId: string,
  swapId: string
}

const Swap = ({
  orderId,
  swapId
}: Props) => {
  const createShipment = useAdminCreateSwapShipment(
    orderId
  )
  // ...

  const handleCreateShipment = (
    fulfillmentId: string
  ) => {
    createShipment.mutate({
      swap_id: swapId,
      fulfillment_id: fulfillmentId,
    }, {
      onSuccess: ({ order }) => {
        console.log(order.swaps)
      }
    })
  }

  // ...
}

export default Swap

fetch(`<BACKEND_URL>/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)
})

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/swaps/<SWAP_ID>/shipments' \
-H 'x-medusa-access-token: <API_TOKEN>'\
-H 'Content-Type: application/json' \
--data-raw '{
    "fulfillment_id": "<FUL_ID>"
}'

This API Route 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.

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 API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.orders.cancelSwapFulfillment(
  orderId, 
  swapId,
  fulfillmentId
)
.then(({ order }) => {
  console.log(order.swaps)
})

import { useAdminCancelSwapFulfillment } from "medusa-react"

type Props = {
  orderId: string,
  swapId: string
}

const Swap = ({
  orderId,
  swapId
}: Props) => {
  const cancelFulfillment = useAdminCancelSwapFulfillment(
    orderId
  )
  // ...

  const handleCancelFulfillment = (
    fulfillmentId: string
  ) => {
    cancelFulfillment.mutate({
      swap_id: swapId,
      fulfillment_id: fulfillmentId,
    })
  }

  // ...
}

export default Swap

fetch(`<BACKEND_URL>/admin/orders/${orderId}/swaps/${swapId}/shipments/${fulfillmentId}/cancel`, {
  credentials: "include",
  method: "POST",
})
.then((response) => response.json())
.then(({ order }) => {
  console.log(order.swaps)
})

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/swaps/<SWAP_ID>/fulfillments/<FUL_ID>/cancel' \
-H 'x-medusa-access-token: <API_TOKEN>'

This API Route 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 API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.orders.cancelSwap(orderId, swapId)
.then(({ order }) => {
  console.log(order.swaps)
})

import { useAdminCancelSwap } from "medusa-react"

type Props = {
  orderId: string,
  swapId: string
}

const Swap = ({
  orderId,
  swapId
}: Props) => {
  const cancelSwap = useAdminCancelSwap(
    orderId
  )
  // ...

  const handleCancel = () => {
    cancelSwap.mutate(swapId, {
      onSuccess: ({ order }) => {
        console.log(order.swaps)
      }
    })
  }

  // ...
}

export default Swap

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

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/swaps/<SWAP_ID>/cancel' \
-H 'x-medusa-access-token: <API_TOKEN>'

This API Route 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
• How to manage returns using admin APIs