How to Manage Orders
In this document, you’ll learn how to manage orders using the admin REST APIs.
Overview
Using the order’s admin REST APIs, you can manage and process the orders in your commerce store.
Scenario
You want to add or use the following admin functionalities:
- List and filter orders.
- Update the order’s details.
- Manage an order’s payment. This includes capturing and refunding an order.
- Manage an order’s fulfillment. That includes creating the fulfillment, canceling it, and creating a shipment for the fulfillment.
- Manage an order’s status, including completing, canceling, and archiving an order.
There are many more functionalities within the order domain related to returns, swaps, claims, and more. Each of these functionalities are explained in their own pages.
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.
List Orders
You can list orders by sending a request to the List Orders API Route:
import { useAdminOrders } from "medusa-react"
const Orders = () => {
const { orders, isLoading } = useAdminOrders()
return (
<div>
{isLoading && <span>Loading...</span>}
{orders && !orders.length && <span>No Orders</span>}
{orders && orders.length > 0 && (
<ul>
{orders.map((order) => (
<li key={order.id}>{order.display_id}</li>
))}
</ul>
)}
</div>
)
}
export default Orders
This API Route doesn't require any path parameters. You can pass it query parameters to filter the orders received.
The request returns an array of orders along with pagination fields.
Filter Orders
This API Route accepts a variety of query parameters that allow you to filter orders. You can check available query parameters in the API reference.
For example, you can filter the orders by one or more status:
import { useAdminOrders } from "medusa-react"
const Orders = () => {
const { orders, isLoading } = useAdminOrders({
status: ["completed"],
// the JS client requires these fields
// to be passed
offset,
limit,
})
return (
<div>
{isLoading && <span>Loading...</span>}
{orders && !orders.length && <span>No Orders</span>}
{orders && orders.length > 0 && (
<ul>
{orders.map((order) => (
<li key={order.id}>{order.display_id}</li>
))}
</ul>
)}
</div>
)
}
export default Orders
You can check available order statuses here.
Another example is filtering the orders by a sales channel:
import { useAdminOrders } from "medusa-react"
const Orders = () => {
const { orders, isLoading } = useAdminOrders({
sales_channel_id: [
salesChannelId,
],
// the JS client requires these fields
// to be passed
offset,
limit,
})
return (
<div>
{isLoading && <span>Loading...</span>}
{orders && !orders.length && <span>No Orders</span>}
{orders && orders.length > 0 && (
<ul>
{orders.map((order) => (
<li key={order.id}>{order.display_id}</li>
))}
</ul>
)}
</div>
)
}
export default Orders
You can also combine filters together:
import { useAdminOrders } from "medusa-react"
const Orders = () => {
const { orders, isLoading } = useAdminOrders({
status: ["completed"],
sales_channel_id: [
salesChannelId,
],
// the JS client requires these fields
// to be passed
offset,
limit,
})
return (
<div>
{isLoading && <span>Loading...</span>}
{orders && !orders.length && <span>No Orders</span>}
{orders && orders.length > 0 && (
<ul>
{orders.map((order) => (
<li key={order.id}>{order.display_id}</li>
))}
</ul>
)}
</div>
)
}
export default Orders
Retrieve an Order
You can retrieve an order by sending a request to the Get an Order API Route:
This API Route requires the order ID to be passed as a path parameter.
The request returns the full order as an object.
Update an Order’s Details
Updating an order ’s details can include updating its:
- Shipping address
- Billing address
- Add new items (this would not invoke the same process and operations as order edits. This would only create the items and attach them to the order).
- Region
- Discounts
- Customer ID
- Payment Method
- Shipping Method
no_notification
property
You can update any of the above details of an order by sending a request to the Update an Order API Route:
import { useAdminUpdateOrder } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const updateOrder = useAdminUpdateOrder(
orderId
)
const handleUpdate = (
email: string
) => {
updateOrder.mutate({
email,
}, {
onSuccess: ({ order }) => {
console.log(order.email)
}
})
}
// ...
}
export default Order
This API Route requires the order’s ID to be passed as a path parameter.
In the request body parameters, you can pass any of the order’s fields mentioned earlier that you want to update. In the example above, you edit the email associated with the order. You can learn about other available request body parameters in the API reference.
The request returns the updated order as an object.
Manage an Order’s Payment
Capture an Order’s Payment
You can capture an order’s payment by sending a request to the Capture Order’s Payment API Route:
import { useAdminCapturePayment } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const capturePayment = useAdminCapturePayment(
orderId
)
// ...
const handleCapture = () => {
capturePayment.mutate(void 0, {
onSuccess: ({ order }) => {
console.log(order.status)
}
})
}
// ...
}
export default Order
This API Route requires the Order ID as a path parameter.
The request returns the updated order as an object.
Refund Payment
You can refund an amount that is less than order.refundable_amount
.
To refund payment, send a request to the Refund Payment API Route:
import { useAdminRefundPayment } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const refundPayment = useAdminRefundPayment(
orderId
)
// ...
const handleRefund = (
amount: number,
reason: string
) => {
refundPayment.mutate({
amount,
reason,
}, {
onSuccess: ({ order }) => {
console.log(order.refunds)
}
})
}
// ...
}
export default Order
fetch(`<BACKEND_URL>/admin/orders/${orderId}/refund`, {
credentials: "include",
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
amount,
reason,
}),
})
.then((response) => response.json())
.then(({ order }) => {
console.log(order.payment_status, order.refunded_total)
})
This API Route requires the order’s ID to be passed as a path parameter.
The following parameters are required in the request body parameters:
amount
: a number indicating the amount to refund.reason
: a string indicating why the refund is being issued.
You can also add other optional body parameters, as explained in the API reference.
The request returns the updated order as an object.
Manage Order Fulfillments
Create a Fulfillment
You can create a fulfillment by sending a request to the Create a Fulfillment API Route:
import { useAdminCreateFulfillment } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const createFulfillment = useAdminCreateFulfillment(
orderId
)
// ...
const handleCreateFulfillment = (
itemId: string,
quantity: number
) => {
createFulfillment.mutate({
items: [
{
item_id: itemId,
quantity,
},
],
}, {
onSuccess: ({ order }) => {
console.log(order.fulfillments)
}
})
}
// ...
}
export default Order
fetch(`<BACKEND_URL>/admin/orders/${orderId}/fulfillment`, {
credentials: "include",
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
items: [
{
itemId,
quantity,
},
],
}),
})
.then((response) => response.json())
.then(({ order }) => {
console.log(order.fulfillment_status, order.fulfillments)
})
This API Route requires the order’s ID to be passed as a path parameter.
In the request body, the items
parameter is required. It’s an array of objects that are the items to fulfill. You can fulfill all items in the order or some items.
Each object in the array must have the following properties:
item_id
: a string indicating the ID of the item to fulfill.quantity
: a number indicating the quantity to fulfill.
You can also pass other optional request body parameters as explained in the API reference.
The request returns the updated order as an object.
Create Shipment
You can create a shipment for a fulfillment by sending a request to the Create Shipment API Route:
import { useAdminCreateShipment } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const createShipment = useAdminCreateShipment(
orderId
)
// ...
const handleCreate = (
fulfillmentId: string
) => {
createShipment.mutate({
fulfillment_id: fulfillmentId,
}, {
onSuccess: ({ order }) => {
console.log(order.fulfillment_status)
}
})
}
// ...
}
export default Order
fetch(`<BACKEND_URL>/admin/orders/${orderId}/shipment`, {
credentials: "include",
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
fulfillment_id,
}),
})
.then((response) => response.json())
.then(({ order }) => {
console.log(order.fulfillment_status, order.fulfillments)
})
This API Route requires passing the order’s ID as a path parameter.
In the request body, the fulfillment_id
parameter is required. Its value is the ID of the fulfillment to create the shipment for. You can also pass other optional body parameters as explained in the API reference.
The request returns the updated order as an object.
Cancel Fulfillment
You can cancel a fulfillment by sending a request to the Cancel Fulfillment API Route:
import { useAdminCancelFulfillment } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const cancelFulfillment = useAdminCancelFulfillment(
orderId
)
// ...
const handleCancel = (
fulfillmentId: string
) => {
cancelFulfillment.mutate(fulfillmentId, {
onSuccess: ({ order }) => {
console.log(order.fulfillments)
}
})
}
// ...
}
export default Order
This API Route requires passing the order’s ID and fulfillment ID as path parameters.
The request returns the updated order as an object.
Completing an Order
You can mark an order completed, changing its status, by sending a request to the Complete an Order API Route:
import { useAdminCompleteOrder } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const completeOrder = useAdminCompleteOrder(
orderId
)
// ...
const handleComplete = () => {
completeOrder.mutate(void 0, {
onSuccess: ({ order }) => {
console.log(order.status)
}
})
}
// ...
}
export default Order
This API Route requires the order ID to be passed as a path parameter.
The request returns the updated order as an object.
Cancel an Order
You can cancel an order by sending a request to the Cancel Order API Route:
import { useAdminCancelOrder } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const cancelOrder = useAdminCancelOrder(
orderId
)
// ...
const handleCancel = () => {
cancelOrder.mutate(void 0, {
onSuccess: ({ order }) => {
console.log(order.status)
}
})
}
// ...
}
export default Order
This API Route requires the order ID to be passed as a path parameter.
The request returns the updated order as an object.
Archive Order
You can archive an order by sending a request to the Archive Order API Route:
import { useAdminArchiveOrder } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const archiveOrder = useAdminArchiveOrder(
orderId
)
// ...
const handleArchivingOrder = () => {
archiveOrder.mutate(void 0, {
onSuccess: ({ order }) => {
console.log(order.status)
}
})
}
// ...
}
export default Order
This API Route requires the order ID to be passed as a path parameter.
The request returns the updated order as an object.