How to Manage Custom Reservations

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

Tip

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.

Note

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

---

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 API Route:

• 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 'x-medusa-access-token: <API_TOKEN>'

This API Route doesn't 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 API Route returns an array of reservations along with pagination parameters.

---

Create a Reservation

Note

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 API Route:

• 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 = (
    locationId: string,
    inventoryItemId: string,
    quantity: number
  ) => {
    createReservation.mutate({
      location_id: locationId,
      inventory_item_id: inventoryItemId,
      quantity,
    }, {
      onSuccess: ({ reservation }) => {
        console.log(reservation.id)
      }
    })
  }

  // ...
}

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 'x-medusa-access-token: <API_TOKEN>' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "location_id": "<LOC_ID>",
        "inventory_item_id": "<INV_ITEM_ID>",
        "quantity": 1
    }'

This API Route 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 API Route:

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

type Props = {
  reservationId: string
}

const Reservation = ({ reservationId }: Props) => {
  const updateReservation = useAdminUpdateReservation(
    reservationId
  )
  // ...

  const handleUpdate = (
    quantity: number
  ) => {
    updateReservation.mutate({
      quantity,
    })
  }

  // ...
}

export default Reservation

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 'x-medusa-access-token: <API_TOKEN>' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "quantity": 3
    }'

This API Route 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 API Route:

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

type Props = {
  reservationId: string
}

const Reservation = ({ reservationId }: Props) => {
  const deleteReservation = useAdminDeleteReservation(
    reservationId
  )
  // ...

  const handleDelete = () => {
    deleteReservation.mutate(void 0, {
      onSuccess: ({ id, object, deleted }) => {
        console.log(id)
      }
    })
  }

  // ...
}

export default Reservation

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 'x-medusa-access-token: <API_TOKEN>'

This API Route 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