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.

Note

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:

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

medusa.admin.orders.list()
.then(({ orders, limit, offset, count }) => {
  console.log(orders.length)
})

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

fetch(`<BACKEND_URL>/admin/orders`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ orders, limit, offset, count }) => {
  console.log(orders.length)
})

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

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:

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

medusa.admin.orders.list({
  status: ["completed"],
  // the JS client requires these fields
  // to be passed
  offset,
  limit,
})
.then(({ orders, limit, offset, count }) => {
  console.log(orders.length)
})

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

fetch(`<BACKEND_URL>/admin/orders?status[]=completed`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ orders, limit, offset, count }) => {
  console.log(orders.length)
})

curl -L -X GET '<BACKEND_URL>/admin/orders?status[]=completed' \
-H 'x-medusa-access-token: <API_TOKEN>'

Note

You can check available order statuses here.

Another example is filtering the orders by a sales channel:

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

medusa.admin.orders.list({
  sales_channel_id: [
    salesChannelId,
  ],
  // the JS client requires these fields
  // to be passed
  offset,
  limit,
})
.then(({ orders, limit, offset, count }) => {
  console.log(orders.length)
})

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

fetch(`<BACKEND_URL>/admin/orders?sales_channel_id[]=${salesChannelId}`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ orders, limit, offset, count }) => {
  console.log(orders.length)
})

curl -L -X GET '<BACKEND_URL>/admin/orders?sales_channel_id[]=<CHANNEL_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>'

You can also combine filters together:

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

medusa.admin.orders.list({
  status: ["completed"],
  sales_channel_id: [
    salesChannelId,
  ],
  // the JS client requires these fields
  // to be passed
  offset,
  limit,
})
.then(({ orders, limit, offset, count }) => {
  console.log(orders.length)
})

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

fetch(`<BACKEND_URL>/admin/orders?status[]=completed&sales_channel_id[]=${salesChannelId}`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ orders, limit, offset, count }) => {
  console.log(orders.length)
})

curl -L -X GET '<BACKEND_URL>/admin/orders?status[]=completed&sales_channel_id[]=<CHANNEL_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>'

---

Retrieve an Order

You can retrieve an order by sending a request to the Get an Order API Route:

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

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

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

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

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 full order as an object.

---

Update an Order’s Details

Updating an order’s details can include updating its:

• Email
• 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:

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

medusa.admin.orders.update(orderId, {
  email,
})
.then(({ order }) => {
  console.log(order.id)
})

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

fetch(`<BACKEND_URL>/admin/orders/${orderId}`, {
  credentials: "include",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email,
  }),
})
.then((response) => response.json())
.then(({ order }) => {
  console.log(order.id)
})

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "email": "user@example.com"
}'

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:

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

medusa.admin.orders.capturePayment(orderId)
.then(({ order }) => {
  console.log(order.payment_status)
})

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

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

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

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:

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

medusa.admin.orders.refundPayment(orderId, {
  amount,
  reason,
})
.then(({ order }) => {
  console.log(order.payment_status, order.refunded_total)
})

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)
})

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/refund' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "amount": 1000,
    "reason": "customer did not like the order"
}'

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:

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

medusa.admin.orders.createFulfillment(orderId, {
  items: [
    {
      itemId,
      quantity,
    },
  ],
})
.then(({ order }) => {
  console.log(order.fulfillment_status, order.fulfillments)
})

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)
})

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/fulfillment' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "items": [
      {
        "item_id": "<ITEM_ID>",
        "quantity": 1
      }
    ]
}'

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:

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

medusa.admin.orders.createShipment(orderId, {
  fulfillment_id,
})
.then(({ order }) => {
  console.log(order.fulfillment_status, order.fulfillments)
})

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)
})

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

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:

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

medusa.admin.orders.cancelFulfillment(orderId, fulfillmentId)
.then(({ order }) => {
  console.log(order.fulfillment_status)
})

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

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

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

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:

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

medusa.admin.orders.complete(orderId)
.then(({ order }) => {
  console.log(order.status)
})

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

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

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/complete' \
-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 updated order as an object.

---

Cancel an Order

You can cancel an order by sending a request to the Cancel Order API Route:

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

medusa.admin.orders.cancel(orderId)
.then(({ order }) => {
  console.log(order.status)
})

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

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

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/cancel' \
-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 updated order as an object.

---

Archive Order

You can archive an order by sending a request to the Archive Order API Route:

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

medusa.admin.orders.archive(orderId)
.then(({ order }) => {
  console.log(order.status)
})

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

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

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/archive' \
-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 updated order as an object.

---

See Also

• How to send an order confirmation email
• How to edit an order