Customizing Scheduler booking flows

By default, Scheduler follows the standard booking flow when a guest creates a booking. You can customize the flow to add or skip steps.

Scheduling component booking flow

Guest

Pick a date

Fires dateSelected.

Guest

Pick and confirm a time

Fires timeslotConfirmed, then opens the booking form.

Guest

Enter and confirm details

Fires detailsConfirmed after the form validates, before Nylas books.

Override detailsConfirmed

Your custom logic

Run your own checks or steps before the booking request.

Booking request

Nylas

Create the booking

Books the slot and fires bookedEventInfo in the component.

booking_type: organizer-confirmation

Pre-booking

Holds the slot with a placeholder until the organizer confirms.

Guest

Confirmation page

The component shows the booked event.

confirmation_redirect_url set

Your confirmation page

Nylas redirects the guest to your URL instead.

Each step in the Scheduling component fires an event you can handle with eventOverrides. Pre-booking and a custom confirmation page are optional.

Diagram as text

• Guest: Pick a date: Fires dateSelected.
• Guest: Pick and confirm a time: Fires timeslotConfirmed, then opens the booking form.
• Guest: Enter and confirm details: Fires detailsConfirmed after the form validates, before Nylas books.
  • Override detailsConfirmed → Your custom logic: Run your own checks or steps before the booking request.
• Nylas: Create the booking: Books the slot and fires bookedEventInfo in the component. (Booking request)
  • booking_type: organizer-confirmation → Pre-booking: Holds the slot with a placeholder until the organizer confirms.
• Guest: Confirmation page: The component shows the booked event.
  • confirmation_redirect_url set → Your confirmation page: Nylas redirects the guest to your URL instead.

Set up pre-booking

You can use pre-bookings to pause the booking flow until the specified action is completed. When you set up a pre-booking, Scheduler adds a placeholder event to the organizer’s calendar, and Scheduler finalizes the booking only when the specified action is completed.

Currently, Scheduler supports organizer-confirmation pre-bookings only.

Set up organizer-confirmed booking

When you set the booking_type to organizer-confirmation and a guest books an event, Scheduler creates a placeholder event marked [PENDING] on the organizer’s calendar, and sends an email notification with a confirmation link. When the organizer clicks the link, they’re redirected to the confirmation request page, where they can either accept or reject the pre-booking.

If the organizer accepts the pre-booking, Scheduler makes a Confirm Booking request to confirm the booking. Nylas deletes the placeholder event and creates a new event for the booking, so the confirmed booking has a new event ID. Scheduler also sends the guest a booking confirmation notification.

If the organizer rejects the pre-booking, Scheduler makes a Confirm Booking request to cancel the booking, and removes the placeholder event from their calendar.

Organizer-confirmed booking flow

Guest

Guest picks a time

The Configuration uses booking_type: organizer-confirmation.

POST /v3/scheduling/bookings

Nylas

Hold the slot

Creates a [PENDING] placeholder event on the organizer's calendar.

Nylas

Ask the organizer

Emails the organizer a confirmation link and sends booking.pending.

Opens the confirmation link

Organizer

Organizer decides

The confirmation page sends a Confirm Booking request.

status: confirmed

Booking confirmed

A new event with a new ID replaces the placeholder. Sends confirmations and booking.created.

status: cancelled

Booking rejected

Nylas deletes the placeholder, emails the guest, and sends booking.cancelled.

The placeholder event holds the slot until the organizer decides. The guest gets no email until the organizer confirms or rejects the booking.

Diagram as text

• Guest: Guest picks a time: The Configuration uses booking_type: organizer-confirmation.
• Nylas: Hold the slot: Creates a [PENDING] placeholder event on the organizer's calendar. (POST /v3/scheduling/bookings)
• Nylas: Ask the organizer: Emails the organizer a confirmation link and sends booking.pending.
• Organizer: Organizer decides: The confirmation page sends a Confirm Booking request. (Opens the confirmation link)
• Ends in one of:
  • status: confirmed → Booking confirmed: A new event with a new ID replaces the placeholder. Sends confirmations and booking.created.
  • status: cancelled → Booking rejected: Nylas deletes the placeholder, emails the guest, and sends booking.cancelled.

To set up organizer-confirmed bookings, you need to create a confirmation request page and add its URL to your Configuration.

Create confirmation request page

To create a confirmation request page, add organizerConfirmationBookingRef to the Scheduling Component and set it to the booking reference for the pre-booking.

<NylasScheduling organizerConfirmationBookingRef="<SCHEDULER_BOOKING_REFERENCE>" />;

You can find the booking reference in multiple places: in the rescheduling or cancellation page URL, or in the notifications you receive when you subscribe to the Scheduler notification triggers.

Add confirmation request page URL to Configuration

Now that you have a confirmation request page, you can add its URL to your Configuration using either the Scheduler API or the Scheduler Editor.

Add URL to Configuration using Scheduler API

To add the confirmation request page URL to your Configuration, make an Update Configuration request. Set the booking_type to organizer-confirmation, and specify the organizer_confirmation_url.

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_booking": {
      "booking_type": "organizer-confirmation"
    },
    "scheduler": {
      "organizer_confirmation_url": "https://www.example.com/confirmation/:booking_ref"
    }
  }'

Add URL to Configuration using Scheduler Editor

You can add the confirmation request page URL to your Configuration by first adding the organizer_confirmation_url property to the Scheduler Editor Component.

HTML/Vanilla JSReact

<html>
  <body>
    <nylas-scheduler-editor />

    <script type="module">
      // ...Scheduler Editor Configuration
      ...
      schedulerEditor.defaultSchedulerConfigState = {
        selectedConfiguration: {
          requires_session_auth: false,
          scheduler: {
            organizer_confirmation_url: `${window.location.origin}/confirmation/:booking_ref`,
            cancellation_url: `${window.location.origin}/cancel/:booking_ref`,
          }
        }
      };

      ...
    </script>
  </body>
</html>

<NylasSchedulerEditor
  ...

  defaultSchedulerConfigState = {
    selectedConfiguration: {
      requires_session_auth: false,
      scheduler: {
        organizer_confirmation_url: `${window.location.origin}/confirmation/:booking_ref`,
        cancellation_url: `${window.location.origin}/cancel/:booking_ref`,
      },
    },
  }
/>

Next, set up an organizer-confirmed booking in the Scheduler Editor. Navigate to the Booking options tab and, under Custom booking flow > When a booking is requested, select Manually accept bookings.

Add confirmation redirect URL

Instead of displaying the default booking confirmation in the Scheduling Component, you can redirect guests to a custom booking confirmation page. For example, your custom page could match your branding and include any preparatory steps or materials the guests will need for the event.

You can specify a confirmation redirect URL by either making an API request or adding it in the Scheduler Editor.

Add confirmation redirect URL using Scheduler API

You can specify the confirmation_redirect_url when you make a Create Configuration or Update Configuration request.

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "scheduler": {
      "confirmation_redirect_url": "https://www.example.com/booking-confirmed"
    }
  }'

Add confirmation redirect URL using Scheduler Editor

By default, the Scheduler Editor includes an option to add a confirmation redirect URL. Navigate to the Booking options tab and, under Custom booking flow > When a booking is confirmed, select Redirect to a custom URL. Enter your URL and save your changes.