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 endpoint:

• 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 'Authorization: Bearer <API_TOKEN>'

This endpoint does not 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 endpoint 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 'Authorization: Bearer <API_TOKEN>'

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 'Authorization: Bearer <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 'Authorization: Bearer <API_TOKEN>'

---

Retrieve an Order

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

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

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

import { useAdminOrder } from "medusa-react"

const Order = () => {
  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 'Authorization: Bearer <API_TOKEN>'

This endpoint 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 endpoint:

• 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"

const UpdateOrder = () => {
  const updateOrder = useAdminUpdateOrder(
    orderId
  )
  // ...

  const handleUpdate = () => {
    updateOrder.mutate({
      email,
    })
  }

  // ...
}

export default UpdateOrder

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 'Authorization: Bearer <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "email": "user@example.com"
}'

This endpoint 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 endpoint:

• 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"

const CapturePayment = () => {
  const capturePayment = useAdminCapturePayment(
    orderId
  )
  // ...

  const handleCapture = () => {
    capturePayment.mutate()
  }

  // ...
}

export default CapturePayment

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 'Authorization: Bearer <API_TOKEN>'

This endpoint 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 endpoint:

• 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"

const RefundPayment = () => {
  const refundPayment = useAdminRefundPayment(
    orderId
  )
  // ...

  const handleRefund = () => {
    refundPayment.mutate({
      amount,
      reason,
    })
  }

  // ...
}

export default RefundPayment

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 'Authorization: Bearer <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "amount": 1000,
    "reason": "customer did not like the order"
}'

This endpoint 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 endpoint:

• 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"

const CreateFuilfillment = () => {
  const createFulfillment = useAdminCreateFulfillment(
    orderId
  )
  // ...

  const handleCreate = () => {
    createFulfillment.mutate({
      items: [
        {
          itemId,
          quantity,
        },
      ],
    })
  }

  // ...
}

export default CreateFuilfillment

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 'Authorization: Bearer <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "items": [
      {
        "item_id": "<ITEM_ID>",
        "quantity": 1
      }
    ]
}'

This endpoint 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 endpoint:

• 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"

const CreateShipment = () => {
  const createShipment = useAdminCreateShipment(
    orderId
  )
  // ...

  const handleCreate = () => {
    createShipment.mutate({
      fulfillment_id,
    })
  }

  // ...
}

export default CreateShipment

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 'Authorization: Bearer <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "fulfillment_id": "<FUL_ID>"
}'

This endpoint 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 endpoint:

• 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"

const CancelFulfillment = () => {
  const cancelFulfillment = useAdminCancelFulfillment(
    orderId
  )
  // ...

  const handleCancel = () => {
    cancelFulfillment.mutate(fulfillment_id)
  }

  // ...
}

export default CancelFulfillment

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 'Authorization: Bearer <API_TOKEN>'

This endpoint 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 endpoint:

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

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

import { useAdminCompleteOrder } from "medusa-react"

const CompleteOrder = () => {
  const completeOrder = useAdminCompleteOrder(
    orderId
  )
  // ...

  const handleComplete = () => {
    completeOrder.mutate()
  }

  // ...
}

export default CompleteOrder

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 'Authorization: Bearer <API_TOKEN>'

This endpoint 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 endpoint:

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

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

import { useAdminCancelOrder } from "medusa-react"

const CancelOrder = () => {
  const cancelOrder = useAdminCancelOrder(
    orderId
  )
  // ...

  const handleCancel = () => {
    cancelOrder.mutate()
  }

  // ...
}

export default CancelOrder

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 'Authorization: Bearer <API_TOKEN>'

This endpoint 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 endpoint:

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

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

import { useAdminArchiveOrder } from "medusa-react"

const ArchiveOrder = () => {
  const archiveOrder = useAdminArchiveOrder(
    orderId
  )
  // ...

  const handleArchive = () => {
    archiveOrder.mutate()
  }

  // ...
}

export default ArchiveOrder

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 'Authorization: Bearer <API_TOKEN>'

This endpoint 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