How to Retrieve Order Details on the Storefront

In this document, you’ll learn the different ways you can retrieve and view a customer’s orders, whether they're a guest customer or logged-in.

Prerequisites

Medusa Components

It's assumed that you already have a Medusa backend installed and set up. If not, you can follow our quickstart guide to get started.

It's also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install the Next.js Starter Template.

JS Client

This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client and JavaScript’s Fetch API.

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.

---

Retrieve Order by ID

Retrieving an order by its ID is useful for different scenarios, such as using an order details page. You can use this method for both logged in and guest customers.

You can retrieve an order by its ID using the Get Order API Route:

• Medusa JS Client
• Medusa React
• Fetch API

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

import { useOrder } from "medusa-react"

type Props = {
  orderId: string
}

const Order = ({ orderId }: Props) => {
  const { 
    order, 
    isLoading, 
  } = useOrder(orderId)

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {order && <span>{order.display_id}</span>}
      
    </div>
  )
}

export default Order

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

This API Route requires the order’s ID to be passed as a path parameter. You can utilize the expand and fields query parameters to select parameters and relations to return.

The request returns the order as an object.

---

Retrieve Order by Display ID

Display IDs allow you to show human-readable IDs to your customers. Retrieving an order by its display ID is useful in many situations, such as allowing customers to look up their orders with a search field. This method of retrieving an order can be used for both logged-in customers and guest customers.

You can retrieve an order by its display ID using the Look Up Order API Route:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.orders.lookupOrder({
  display_id: 1,
  email: "user@example.com",
})
.then(({ order }) => {
  console.log(order.id)
})

import { useOrders } from "medusa-react"

type Props = {
  displayId: number
  email: string
}

const Order = ({
  displayId,
  email
}: Props) => {
  const { 
    order, 
    isLoading, 
  } = useOrders({
    display_id: displayId,
    email,
  })

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {order && <span>{order.display_id}</span>}
      
    </div>
  )
}

export default Order

fetch(`<BACKEND_URL>/store/orders?display_id=1&email=user@example.com`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ order }) => {
  console.log(order.id)
})

This API Route requires two query parameters:

• display_id: a string indicating display ID of the order. If you already have an order object, you can retrieve the display ID using order.display_id.
• email: a string indicating the email associated with the order.

You can pass other query parameters to filter the orders even further, and the API Route will return the first order that matches the filters. Learn more about available query parameters in the API reference.

The request returns the order as an object.

---

Retrieve Order by Cart ID

In certain scenarios, you may need to retrieve an order’s details using the ID of the cart associated with the order. This can be useful when showing a success page after a cart is completed and an order is placed.

You can retrieve an order by the cart ID using the Get by Cart ID API Route:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.orders.retrieveByCartId(cartId)
.then(({ order }) => {
  console.log(order.id)
})

import { useCartOrder } from "medusa-react"

type Props = {
  cartId: string
}

const Order = ({ cartId }: Props) => {
  const { 
    order, 
    isLoading, 
  } = useCartOrder(cartId)

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {order && <span>{order.display_id}</span>}
      
    </div>
  )
}

export default Order

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

This API Route requires the ID of the cart as a path parameter.

The request returns the order as an object.

---

Retrieve a Customer’s Orders

When a customer is logged in, you can retrieve a list of their orders. This is typically useful to show a customer their orders in their profile. This method can only be used for logged-in customers.

You can learn how to retrieve a customer’s orders in the How to Implement Customer Profiles documentation.

---

See Also

• How to handle order edits in the storefront
• How to implement claim order flow in the storefront