Skip to main content

Cal.com workflow guide

How to Test Cal.com Slot Reservation Locally

The reservation path is where scheduling APIs start feeling real: available slots, temporary holds, expiration windows, and the final booking handoff.

Apr 20, 2026FetchSandbox Engineering

A plain booking API demo is not enough when traffic is real. The moment a scheduling product adds temporary holds, reservation expiry, and conflict checks, the useful workflow becomes narrower and more time-sensitive.

The discovered Cal.com reservation workflow is a good example. It is not just POST /v2/bookings. It is slot lookup, reservation creation, reservation verification, and then the final booking request while that hold is still valid.

The slot reservation flow worth testing

  1. Get available slots: GET /v2/slots. Expected status 200. Start from the current availability view instead of assuming the UI and API agree.
  2. Reserve a slot: POST /v2/slots/reservations. Expected status 201. Hold a slot temporarily while the user finishes the rest of the booking form.
  3. Get reserved slot details: GET /v2/slots/reservations/{uid}. Expected status 200. Check whether the reservation is still active and when that hold expires.
  4. Create booking from reservation: POST /v2/bookings. Expected status 201. Convert the held slot into a real booking before the reservation window closes.

Why this flow matters more than a simple booking happy path

Reservation logic exists to prevent double-booking, but it also creates a new class of bugs. The slot was available. Then it was held. Then the hold expired. Then the booking request arrived a little too late. That sequence is exactly where static mocks stop being useful.

This is also the kind of flow that broad API docs rarely explain well. The endpoint docs can all be correct individually and still leave you guessing about the timing and state assumptions between them.

Failure modes to force before production

  • the reservation expires before the booking request is sent
  • the slot looked available, then disappeared because of another calendar conflict
  • the reservation uid is wrong or stale
  • the UI assumes a hold exists but the API already released it
  • the final booking path succeeds in isolation but not after a real reservation step

These are the bugs that usually show up only after real users start competing for the same availability windows. By then the problem is no longer "does the endpoint work?" It is "does the whole reservation-to-booking handoff still hold up under real timing?"

Where this fits in the broader Cal.com testing story

If you want the full create, fetch, reschedule, cancel sequence, open How to Test Cal.com Booking Lifecycle Locally. If you want the broader reference, open the Cal.com docs portal.

The useful takeaway is simple: test the reservation step as part of the booking flow, not as a side note, because that temporary hold is exactly what stands between a clean demo and a double-booking bug.