How to Manage Custom Reservations

In this document, you’ll learn how to manage custom reservations of a product variant using the admin APIs.

Although this guide covers how to manage custom reservations of product variants, you can create custom reservations for any entity that is associated with an Inventory Item.

Overview

When an order is created, reservations are created for the items in that order automatically. However, Medusa also provides the capability to create custom reservations that aren’t related to any order. Custom reservations allow you to allocate quantities of a product variant manually. You can do that using the Reservations admin APIs.

The functionalities in this guide apply to all types of reservations, including those associated with an order and those that aren’t.

Scenario

You want to add or use the following admin functionalities:

• List reservations, including custom reservations or those associated with orders.
• Manage a reservation, including creating, updating, and deleting a reservation.

You can check the API reference for all available Reservations endpoints.

---

Prerequisites

Medusa Components

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

Required Module

This guide assumes you have a stock location and inventory modules installed. You can use Medusa’s Stock Location and Inventory modules or create your own modules.

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 Reservations

You can list all reservations in your store by sending a request to the List Reservations endpoint:

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

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

import { useAdminReservations } from "medusa-react"

const Reservations = () => {
  const { reservations, isLoading } = useAdminReservations()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {reservations && !reservations.length && (
        <span>No Reservations</span>
      )}
      {reservations && reservations.length > 0 && (
        <ul>
          {reservations.map((reservation) => (
            <li key={reservation.id}>{reservation.quantity}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default Reservations

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

curl -L -X GET '<BACKEND_URL>/admin/reservations' \
-H 'Authorization: Bearer <API_TOKEN>'

This endpoint does not require any query or path parameters. You can pass it query parameters for filtering or pagination purposes. Check out the API reference for a list of accepted query parameters.

This endpoint returns an array of reservations along with pagination parameters.

---

Create a Reservation

Before you create a reservation for a product variant, make sure you’ve created an inventory item for that variant. You can learn how to do that in this guide.

You can create a reservation by sending a request to the Create Reservation endpoint:

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

medusa.admin.reservations.create({
  location_id,
  inventory_item_id,
  quantity,
})
.then(({ reservation }) => {
  console.log(reservation.id)
})

import { useAdminCreateReservation } from "medusa-react"

const CreateReservation = () => {
  const createReservation = useAdminCreateReservation()
  // ...

  const handleCreate = () => {
    createReservation.mutate({
      location_id,
      inventory_item_id,
      quantity,
    })
  }

  // ...
}

export default CreateReservation

fetch(`<BACKEND_URL>/admin/reservations`, {
  credentials: "include",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    location_id,
    inventory_item_id,
    quantity,
  }),
})
.then((response) => response.json())
.then(({ reservation }) => {
  console.log(reservation.id)
})

curl -L -X POST '<BACKEND_URL>/admin/reservations' \
     -H 'Authorization: Bearer <API_TOKEN>' \
     -H 'Content-Type: application/json' \
     --data-raw '{
        "location_id": "<LOC_ID>",
        "inventory_item_id": "<INV_ITEM_ID>",
        "quantity": 1
     }'

This endpoint requires the following body parameters:

• location_id: The ID of the location the reservation is created in.
• inventory_item_id: The ID of the inventory item the product variant is associated with.
• quantity: The quantity to allocate.

The request returns the created reservation as an object.

---

Update a Reservation

You can update a reservation by sending a request to the Update Reservation endpoint:

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

medusa.admin.reservations.update(reservationId, {
  quantity,
})
.then(({ reservation }) => {
  console.log(reservation.id)
})

import { useAdminUpdateReservation } from "medusa-react"

const UpdateReservation = () => {
  const updateReservation = useAdminUpdateReservation(
    reservationId
  )
  // ...

  const handleCreate = () => {
    updateReservation.mutate({
      quantity,
    })
  }

  // ...
}

export default UpdateReservation

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

curl -L -X POST '<BACKEND_URL>/admin/reservations/<RESERVATION_ID>' \
     -H 'Authorization: Bearer <API_TOKEN>' \
     -H 'Content-Type: application/json' \
     --data-raw '{
        "quantity": 3
     }'

This endpoint requires the ID of the reservation as a path parameter.

In the request body parameters, you can optionally pass any of the following parameters to make updates to the reservation:

• quantity: The quantity that should be reserved.
• location_id: The ID of the location that the product variant should be allocated from.
• metadata: set or change the reservation’s metadata.

The request returns the updated reservation as an object.

---

Delete a Reservation

You can delete a reservation by sending a request to the Delete Reservation endpoint:

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

medusa.admin.reservations.delete(reservationId)
.then(({ id, object, deleted }) => {
  console.log(id)
})

import { useAdminDeleteReservation } from "medusa-react"

const DeleteReservation = () => {
  const deleteReservation = useAdminDeleteReservation(
    reservationId
  )
  // ...

  const handleDelete = () => {
    deleteReservation.mutate()
  }

  // ...
}

export default DeleteReservation

fetch(`<BACKEND_URL>/admin/reservations/${reservationId}`, {
  credentials: "include",
  method: "DELETE",
})
.then((response) => response.json())
.then(({ id, object, deleted }) => {
  console.log(id)
})

curl -L -X DELETE '<BACKEND_URL>/admin/reservations/<RESERVATION_ID>' \
     -H 'Authorization: Bearer <API_TOKEN>'

This endpoint requires the reservation ID to be passed as a path parameter.

The request returns the following fields:

• id: The ID of the reservation.
• object: The type of object that was removed. In this case, the value will be reservation.
• deleted: A boolean value indicating whether the reservation was successfully deleted.

---

See Also

• How to manage inventory items
• How to manage stock locations