Orders
Queries and Mutations listed here are used to send requests to the Admin Order API Routes.
All hooks listed require authentication.
Orders are purchases made by customers, typically through a storefront using cart. Managing orders include managing fulfillment, payment, claims, reservations, and more.
Related Guide: How to manage orders.
Mutations
useAdminUpdateOrder
This hook updates an order's details.
Example
import React from "react"
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
Hook Parameters
id
stringRequiredMutation Function Parameters
The details to update of the order.
Mutation Function Returned Data
The order's details.
useAdminCancelOrder
This hook cancels an order and change its status. This will also cancel any associated fulfillments and payments, and it may fail if the payment or fulfillment Provider is unable to cancel the payment/fulfillment.
Example
import React from "react"
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
Hook Parameters
id
stringRequiredMutation Function Returned Data
The order's details.
useAdminCompleteOrder
This hook completes an order and change its status. A canceled order can't be completed.
Example
import React from "react"
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
Hook Parameters
id
stringRequiredMutation Function Returned Data
The order's details.
useAdminCapturePayment
This hook captures all the payments associated with an order. The payment of canceled orders can't be captured.
Example
import React from "react"
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
Hook Parameters
id
stringRequiredMutation Function Returned Data
The order's details.
useAdminRefundPayment
This hook refunds an amount for an order. The amount must be less than or equal the refundable_amount
of the order.
Example
import React from "react"
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
Hook Parameters
id
stringRequiredMutation Function Parameters
The details of the order refund.
Mutation Function Returned Data
The order's details.
useAdminCreateFulfillment
This hook creates a Fulfillment of an Order using the fulfillment provider, and change the order's
fulfillment status to either partially_fulfilled
or fulfilled
, depending on
whether all the items were fulfilled.
Example
import React from "react"
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
Hook Parameters
orderId
stringRequiredMutation Function Parameters
The details of the fulfillment to be created.
Mutation Function Returned Data
The order's details.
useAdminCancelFulfillment
This hook cancels an order's fulfillment and change its fulfillment status to canceled
.
Example
import React from "react"
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
Hook Parameters
orderId
stringRequiredMutation Function Parameters
string
stringRequiredMutation Function Returned Data
The order's details.
useAdminCreateShipment
This hook creates a shipment and mark a fulfillment as shipped. This changes the order's fulfillment status to either
partially_shipped
or shipped
, depending on whether all the items were shipped.
Example
import React from "react"
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
Hook Parameters
orderId
stringRequiredMutation Function Parameters
The details of the shipment to create.
Mutation Function Returned Data
The order's details.
useAdminRequestReturn
This hook requests and create a return for items in an order. If the return shipping method is specified, it will be automatically fulfilled.
Example
import React from "react"
import { useAdminRequestReturn } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const requestReturn = useAdminRequestReturn(
orderId
)
// ...
const handleRequestingReturn = (
itemId: string,
quantity: number
) => {
requestReturn.mutate({
items: [
{
item_id: itemId,
quantity
}
]
}, {
onSuccess: ({ order }) => {
console.log(order.returns)
}
})
}
// ...
}
export default Order
Hook Parameters
orderId
stringRequiredMutation Function Parameters
The details of the requested return.
Mutation Function Returned Data
The order's details.
useAdminAddShippingMethod
This hook adds a shipping method to an order. If another shipping method exists with the same shipping profile, the previous shipping method will be replaced.
Example
import React from "react"
import { useAdminAddShippingMethod } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const addShippingMethod = useAdminAddShippingMethod(
orderId
)
// ...
const handleAddShippingMethod = (
optionId: string,
price: number
) => {
addShippingMethod.mutate({
option_id: optionId,
price
}, {
onSuccess: ({ order }) => {
console.log(order.shipping_methods)
}
})
}
// ...
}
export default Order
Hook Parameters
orderId
stringRequiredMutation Function Parameters
The shipping method's details.
Mutation Function Returned Data
The order's details.
useAdminArchiveOrder
The hook archives an order and change its status.
Example
import React from "react"
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
Hook Parameters
id
stringRequiredMutation Function Returned Data
The order's details.
Queries
useAdminOrders
This hook retrieves a list of orders. The orders can be filtered by fields such as status
or display_id
passed
in the query
parameter. The order can also be paginated.
Example
To list orders:
import React from "react"
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
You can use the query
parameter to pass filters and specify relations that should be retrieved within the orders. In addition,
By default, only the first 50
records are retrieved. You can control pagination by specifying the limit
and offset
properties:
import React from "react"
import { useAdminOrders } from "medusa-react"
const Orders = () => {
const {
orders,
limit,
offset,
isLoading
} = useAdminOrders({
expand: "customers",
limit: 20,
offset: 0
})
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
Hook Parameters
query
AdminGetOrdersParamsFilters and pagination configurations applied on the retrieved orders.
query
AdminGetOrdersParamsQuery Returned Data
limit
numberRequiredoffset
numberRequiredcount
numberRequiredAn array of order details.
useAdminOrder
This hook retrieve an order's details.
Example
A simple example that retrieves an order by its ID:
import React from "react"
import { useAdminOrder } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const {
order,
isLoading,
} = useAdminOrder(orderId)
return (
<div>
{isLoading && <span>Loading...</span>}
{order && <span>{order.display_id}</span>}
</div>
)
}
export default Order
To specify relations that should be retrieved:
import React from "react"
import { useAdminOrder } from "medusa-react"
const Order = (
orderId: string
) => {
const {
order,
isLoading,
} = useAdminOrder(orderId, {
expand: "customer"
})
return (
<div>
{isLoading && <span>Loading...</span>}
{order && <span>{order.display_id}</span>}
</div>
)
}
export default Order
Hook Parameters
id
stringRequiredquery
FindParamsConfigurations to apply on the retrieved order.
query
FindParams