Bookings hooks

This is now deprecated and under maintenance for existing users only - no new customers can sign up for the platform plan

Optimize your development workflow using our custom hooks. Our custom hooks are designed to simplify the integration of the Cal.com API into your products. With these hooks, you can effortlessly manage state, handle side effects, and optimize performance, allowing you to focus on building exceptional user experiences without the hassle of complex API interactions. Below is a list of hooks you can find that are associated with bookings. Notably, all of these hooks are available only for platform customers.

1. get all bookings - `useBookings`

The useBookings hook returns an array of bookings that belong to the user whose access token is passed to <CalProvider>. You can filter bookings by status, event type id, attendee email etc. - see this class for filters you can pass to the hook. Below code snippet shows how to use the useBookings hook to fetch bookings for a specific user using take, skip and status filters:

import { useBookings } from "@calcom/atoms";

export default function Bookings() {
  const { isLoading: isLoadingUpcomingBookings, data: upcomingBookings } = useBookings({
    take: 50,
    skip: 0,
    status: ["upcoming"],
  });

  return (
    <>
      <h1>Upcoming bookings</h1>
      {isLoadingUpcomingBookings && <p>Loading...</p>}
      {!isLoadingUpcomingBookings && !upcomingBookings && <p>No upcoming bookings found</p>}
      {!isLoading &&
        upcomingBookings &&
        (Boolean(upcomingBookings?.length)) &&
        [...upcomingBookings].map((booking) => {
            return (
                <div key={booking.id}><h1>{booking.title}</h1></div>
            );
       })}
    </>
  );
}

2. get specific booking - `useBooking`

The useBooking hook returns detailed information about a single booking. Simply provide the booking’s unique identifier (bookingUid) as a parameter to fetch its associated data. Below code snippet shows how to use the useBooking hook to fetch a specific booking for a user.

import { useBooking } from "@calcom/atoms";

export default function Booking() {
  const { isLoading: isLoadingBooking, data: booking } = useBooking("nChHoxEm1GXVPzi7TNAuWc");

  return (
    <>
      {isLoadingBooking && <p>Loading...</p>}
      {!isLoadingBooking && !booking && <p>No booking found</p>}
      {!isLoading &&
        !!booking &&
        return (
          <div>Title: {booking.title}</div>
        )
        }
    </>
  );
}

3. cancel booking - `useCancelBooking`

The useCancelBooking hook allows you to cancel a booking. This hook returns a mutation function that handles the cancellation process. To cancel a booking, you’ll need to provide at least the booking’s unique identifier (uid). While the uid is the only mandatory parameter, you can enhance the cancellation process by including optional parameters such as cancellationReason to specify why the booking is being canceled, and allRemainingBookings to specify whether to cancel all future recurring bookings. Below code snippet shows how to use the useCancelBooking hook to cancel a booking for a user.

import { useCancelBooking } from "@calcom/atoms";

export default function CancelBooking() {
    const { mutate: cancelBooking } = useCancelBooking({
    onSuccess: () => {
      console.log("Booking canceled successfully!")
    },
  });

  return (
    <>
      <button onClick={() => {
          cancelBooking({
            uid: "6L6ADNpVHwLX25V8wXKsBr",
            cancellationReason: "User request",
            allRemainingBookings: true,
          })
        }}>
        Cancel booking
      </button>
    </>
  );
}

4. get all bookings of a user as an organization admin - `useOrganizationUserBookings`

The useBookings hooks returns bookings of user associated with the access token passed to the <CalProvider>, but this hook allows organization admins to fetch bookings of any organization member. The access token passed to the <CalProvider> must belong to a managed user who is an organization admin. That means you have to create a managed user and then add an accepted membership with an admin or owner role by making a request to the organizations memberships endpoint. Example body:

{
  "userId": 1006,
  "accepted": true,
  "role": "ADMIN"
}

then you have to pass the access token of this managed user to the CalProvider to then finally be able to use the “useOrganizationUserBookings” by specifying “userId” which will return an array of that user’s bookings. You can filter bookings by status, event type id, attendee email etc. - see this class for filters you can pass to the hook. Below code snippet shows how to use the “useOrganizationUserBookings” hook to fetch bookings for a specific user using take, skip and status filters:

import { useOrganizationUserBookings } from "@calcom/atoms";

export default function Bookings() {
  const someUserId = 1218;

  const { isLoading: isLoadingUpcomingBookings, data: upcomingBookings } = useOrganizationUserBookings(someUserId, {
    take: 50,
    skip: 0,
    status: ["upcoming"],
  });

  return (
    <>
      <h1>Upcoming bookings</h1>
      {isLoadingUpcomingBookings && <p>Loading...</p>}
      {!isLoadingUpcomingBookings && !upcomingBookings && <p>No upcoming bookings found</p>}
      {!isLoading &&
        upcomingBookings &&
        (Boolean(upcomingBookings?.length)) &&
        [...upcomingBookings].map((booking) => {
            return (
                <div key={booking.id}><h1>{booking.title}</h1></div>
            );
       })}
    </>
  );
}

5. get all organization bookings as an organization admin - `useOrganizationBookings`

The useBookings hooks returns bookings of user associated with the access token passed to the <CalProvider>, but this hook allows organization admins to fetch bookings of the whole organization. The access token passed to the <CalProvider> must belong to a managed user who is an organization admin. That means you have to create a managed user and then add an accepted membership with an admin or owner role by making a request to the organizations memberships endpoint. Example body:

{
  "userId": 1006,
  "accepted": true,
  "role": "ADMIN"
}

then you have to pass the access token of this managed user to the CalProvider to then finally be able to use the “useOrganizationBookings” which will return an array of organization bookings. You can filter bookings by status, user ids, event type ids, attendee email etc. - see this class for filters you can pass to the hook + you can use “userIds” filter like in example below. Below code snippet shows how to use the “useOrganizationBookings” hook to fetch bookings for a specific users using take, skip and userIds filters:

import { useOrganizationBookings } from "@calcom/atoms";

export default function Bookings() {
  const { isLoading: isLoadingUpcomingBookings, data: upcomingBookings } = useOrganizationBookings({
    take: 50,
    skip: 0,
    userIds: [10, 11],
  });

  return (
    <>
      <h1>Upcoming bookings</h1>
      {isLoadingUpcomingBookings && <p>Loading...</p>}
      {!isLoadingUpcomingBookings && !upcomingBookings && <p>No upcoming bookings found</p>}
      {!isLoading &&
        upcomingBookings &&
        (Boolean(upcomingBookings?.length)) &&
        [...upcomingBookings].map((booking) => {
            return (
                <div key={booking.id}><h1>{booking.title}</h1></div>
            );
       })}
    </>
  );
}

Previous: Troubleshooter

Debug availability issues

Next: Event Types Hooks

Hooks for event types

Getting Started

CORE

CALENDARS

EVENT TYPES & AUTOMATION

TEAMS

ORGANIZATIONS

AUTH & ACCESS

DEPRECATED

1. get all bookings - `useBookings`

2. get specific booking - `useBooking`

3. cancel booking - `useCancelBooking`

4. get all bookings of a user as an organization admin - `useOrganizationUserBookings`

5. get all organization bookings as an organization admin - `useOrganizationBookings`

Previous: Troubleshooter

Next: Event Types Hooks

​1. get all bookings - useBookings

​2. get specific booking - useBooking

​3. cancel booking - useCancelBooking

​4. get all bookings of a user as an organization admin - useOrganizationUserBookings

​5. get all organization bookings as an organization admin - useOrganizationBookings

Previous: Troubleshooter

Next: Event Types Hooks

1. get all bookings - `useBookings`

2. get specific booking - `useBooking`

3. cancel booking - `useCancelBooking`

4. get all bookings of a user as an organization admin - `useOrganizationUserBookings`

5. get all organization bookings as an organization admin - `useOrganizationBookings`