# Create, reschedule, and cancel bookings

Source: https://developer.nylas.com/docs/cookbook/use-cases/build/manage-bookings/

A booking page is only half the job. Once a configuration exists, your app has to actually create bookings when someone picks a slot, and then handle the reschedules and cancellations that follow. Doing that against each provider's calendar by hand is exactly what Scheduler avoids.

The Nylas bookings API manages that lifecycle through one resource. You create a booking against a configuration, then reschedule, confirm, or cancel it with calls keyed on the booking ID.

## How do I create a booking?

Send a `POST /v3/scheduling/bookings` request referencing the `configuration_id` from your Scheduler configuration, along with the chosen `start_time`, `end_time`, and the guest's details. Both times must match a valid availability slot. Nylas books the slot on the organizer's calendar and returns a `booking_id`. The slot length comes from the configuration, so a config set to 30 minutes produces a 30 minute event.

```bash
curl --compressed --request POST \
  --url 'https://api.us.nylas.com/v3/scheduling/bookings' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_time": 1709643600,
    "end_time": 1709645400,
    "participants": [],
    "guest": {
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  }'

```

## How do I reschedule, confirm, or cancel a booking?

The booking ID gives you 3 lifecycle actions on `/v3/scheduling/bookings/{booking_id}`: `PATCH` reschedules it to a new time, `PUT` confirms or cancels a pending booking, and `DELETE` deletes it. Each updates or cancels the event on the organizer's provider calendar across all 4 providers, so a cancellation removes the event in one call.

Use `PATCH` when a guest moves their slot and `DELETE` when they drop out, rather than editing the underlying calendar event directly, so Scheduler keeps its own state consistent.

## Things to know about bookings

Bookings flow through the configuration, so their behavior follows what you set there. A booking lands on the organizer's calendar across all 4 providers, and the meeting length and conferencing come from the configuration rather than the booking call, which keeps every booking against a page consistent. Pending bookings wait for a `PUT` confirmation when your flow requires approval.

To map booking IDs back to calendar events, see [retrieve booking IDs](/docs/v3/scheduler/retrieve-booking-ids/). The booking lifecycle also emits the `booking.created`, `booking.rescheduled`, and `booking.cancelled` webhooks, 3 of the 5 booking triggers you can subscribe to (the others are `booking.pending` and `booking.reminder`).

## What's next

- [Create a Scheduler booking config](/docs/cookbook/use-cases/build/scheduler-booking-config/) to define the page bookings run against
- [Scheduler overview](/docs/v3/scheduler/) for the full bookings reference
- [Retrieve booking IDs](/docs/v3/scheduler/retrieve-booking-ids/) to link bookings to calendar events
- [Get real-time updates with webhooks](/docs/cookbook/use-cases/build/realtime-webhooks/) for booking.created and booking.cancelled events