Orders

Queries and Mutations listed here are used to send requests to the Admin Order API Routes.

All hooks listed require user 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

idstringRequired

The order's ID.

Mutation Function Parameters

AdminPostOrdersOrderReqAdminPostOrdersOrderReqRequired

The details to update of the order.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

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

idstringRequired

The order's ID.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

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

idstringRequired

The order's ID.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

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

idstringRequired

The order's ID.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

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

idstringRequired

The order's ID.

Mutation Function Parameters

AdminPostOrdersOrderRefundsReqAdminPostOrdersOrderRefundsReqRequired

The details of the order refund.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

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

orderIdstringRequired

The order's ID.

Mutation Function Parameters

AdminPostOrdersOrderFulfillmentsReqAdminPostOrdersOrderFulfillmentsReqRequired

The details of the fulfillment to be created.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

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

orderIdstringRequired

The order's ID.

Mutation Function Parameters

stringstringRequired

The fulfillment's ID.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

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

orderIdstringRequired

The order's ID.

Mutation Function Parameters

AdminPostOrdersOrderShipmentReqAdminPostOrdersOrderShipmentReqRequired

The details of the shipment to create.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

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

orderIdstringRequired

The order's ID.

Mutation Function Parameters

AdminPostOrdersOrderReturnsReqAdminPostOrdersOrderReturnsReqRequired

The details of the requested return.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

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

orderIdstringRequired

The order's ID.

Mutation Function Parameters

AdminPostOrdersOrderShippingMethodsReqAdminPostOrdersOrderShippingMethodsReqRequired

The shipping method's details.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

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

idstringRequired

The order's ID.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

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

queryAdminGetOrdersParams

Filters and pagination configurations applied on the retrieved orders.

Query Returned Data

countnumberRequired

The total number of items available.

limitnumberRequired

The maximum number of items that can be returned in the list.

offsetnumberRequired

The number of items skipped before the returned items in the list.

ordersOrder[]Required

An 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

idstringRequired

The order's ID.

queryFindParams

Configurations to apply on the retrieved order.

Query Returned Data

orderOrderRequired

Order details.