Overview

Availability schedules define when bookings can be made. Configure working hours, time zones, and exceptions for holidays or time off.

Creating Schedules

Basic Schedule

TypeScript:

const schedule = await client.calendar.schedules.create({
  name: 'Work Hours',
  timezone: 'America/New_York',
  isDefault: true,
  availability: [
    { day: 'MONDAY', startTime: '09:00', endTime: '17:00' },
    { day: 'TUESDAY', startTime: '09:00', endTime: '17:00' },
    { day: 'WEDNESDAY', startTime: '09:00', endTime: '17:00' },
    { day: 'THURSDAY', startTime: '09:00', endTime: '17:00' },
    { day: 'FRIDAY', startTime: '09:00', endTime: '17:00' },
  ],
});

Python:

schedule = client.calendar.schedules.create(
    name="Work Hours",
    timezone="America/New_York",
    is_default=True,
    availability=[
        {"day": "MONDAY", "startTime": "09:00", "endTime": "17:00"},
        {"day": "TUESDAY", "startTime": "09:00", "endTime": "17:00"},
        {"day": "WEDNESDAY", "startTime": "09:00", "endTime": "17:00"},
        {"day": "THURSDAY", "startTime": "09:00", "endTime": "17:00"},
        {"day": "FRIDAY", "startTime": "09:00", "endTime": "17:00"},
    ],
)

Multiple Time Blocks

Define non-contiguous hours:

const schedule = await client.calendar.schedules.create({
  name: 'Split Schedule',
  timezone: 'America/Los_Angeles',
  availability: [
    // Morning block
    { day: 'MONDAY', startTime: '09:00', endTime: '12:00' },
    // Afternoon block (after lunch)
    { day: 'MONDAY', startTime: '13:00', endTime: '17:00' },
 
    { day: 'TUESDAY', startTime: '09:00', endTime: '12:00' },
    { day: 'TUESDAY', startTime: '13:00', endTime: '17:00' },
 
    // Different hours on Wednesday
    { day: 'WEDNESDAY', startTime: '10:00', endTime: '14:00' },
  ],
});

Day Values

Available day constants:

Value	Description
`SUNDAY`	Sunday
`MONDAY`	Monday
`TUESDAY`	Tuesday
`WEDNESDAY`	Wednesday
`THURSDAY`	Thursday
`FRIDAY`	Friday
`SATURDAY`	Saturday

Time Zones

Always specify the schedule timezone:

const schedule = await client.calendar.schedules.create({
  name: 'EU Hours',
  timezone: 'Europe/London',
  availability: [
    { day: 'MONDAY', startTime: '09:00', endTime: '17:00' },
    // ...
  ],
});

Common Timezones

Region	Timezone
US Eastern	`America/New_York`
US Central	`America/Chicago`
US Mountain	`America/Denver`
US Pacific	`America/Los_Angeles`
UK	`Europe/London`
Central Europe	`Europe/Berlin`
India	`Asia/Kolkata`
Japan	`Asia/Tokyo`
Australia	`Australia/Sydney`

Date Overrides

Override availability for specific dates:

Block Dates

Make dates unavailable:

await client.calendar.schedules.addOverride(schedule.id, {
  date: '2024-12-25',
  isAvailable: false,
  reason: 'Christmas Day',
});
 
// Block date range
await client.calendar.schedules.addOverrides(schedule.id, [
  { date: '2024-12-24', isAvailable: false, reason: 'Christmas Eve' },
  { date: '2024-12-25', isAvailable: false, reason: 'Christmas Day' },
  { date: '2024-12-26', isAvailable: false, reason: 'Boxing Day' },
]);

Custom Hours

Override with different hours:

await client.calendar.schedules.addOverride(schedule.id, {
  date: '2024-01-15',
  isAvailable: true,
  availability: [
    { startTime: '10:00', endTime: '14:00' },
  ],
  reason: 'Shortened day',
});

Add Availability on Off Days

Open up normally unavailable days:

// Open Saturday hours for a special event
await client.calendar.schedules.addOverride(schedule.id, {
  date: '2024-02-10',
  isAvailable: true,
  availability: [
    { startTime: '10:00', endTime: '16:00' },
  ],
  reason: 'Special Saturday event',
});

Managing Overrides

List Overrides

const overrides = await client.calendar.schedules.listOverrides(schedule.id, {
  startDate: '2024-01-01',
  endDate: '2024-12-31',
});
 
for (const override of overrides) {
  console.log(`${override.date}: ${override.isAvailable ? 'Custom hours' : 'Blocked'}`);
}

Remove Override

await client.calendar.schedules.removeOverride(schedule.id, override.id);

Linking Schedules to Event Types

// Link when creating
const eventType = await client.calendar.eventTypes.create({
  title: 'Meeting',
  scheduleId: schedule.id,
});
 
// Or update existing
await client.calendar.eventTypes.update(eventType.id, {
  scheduleId: schedule.id,
});

Multiple Schedules

Create different schedules for different purposes:

// Client meetings - business hours
const clientSchedule = await client.calendar.schedules.create({
  name: 'Client Meetings',
  timezone: 'America/New_York',
  availability: [
    { day: 'MONDAY', startTime: '10:00', endTime: '16:00' },
    { day: 'TUESDAY', startTime: '10:00', endTime: '16:00' },
    { day: 'WEDNESDAY', startTime: '10:00', endTime: '16:00' },
    { day: 'THURSDAY', startTime: '10:00', endTime: '16:00' },
  ],
});
 
// Internal meetings - wider availability
const internalSchedule = await client.calendar.schedules.create({
  name: 'Internal Meetings',
  timezone: 'America/New_York',
  availability: [
    { day: 'MONDAY', startTime: '08:00', endTime: '18:00' },
    { day: 'TUESDAY', startTime: '08:00', endTime: '18:00' },
    { day: 'WEDNESDAY', startTime: '08:00', endTime: '18:00' },
    { day: 'THURSDAY', startTime: '08:00', endTime: '18:00' },
    { day: 'FRIDAY', startTime: '08:00', endTime: '18:00' },
  ],
});

Getting Available Slots

Query available times for booking:

const availability = await client.calendar.availability.get({
  eventTypeId: 'evt_xxx',
  startDate: '2024-01-15',
  endDate: '2024-01-22',
  timezone: 'America/New_York',
});
 
// Response structure
{
  days: [
    {
      date: '2024-01-15',
      slots: [
        { startTime: '09:00', endTime: '09:30' },
        { startTime: '09:30', endTime: '10:00' },
        { startTime: '10:00', endTime: '10:30' },
        // ...
      ]
    },
    // ...
  ]
}

Filter by Duration

// Get slots for specific duration
const availability = await client.calendar.availability.get({
  eventTypeId: 'evt_xxx',
  startDate: '2024-01-15',
  endDate: '2024-01-22',
  duration: 60, // For event types with multiple durations
});

Calendar Blocking

Block time when external calendars have events:

// When calendar sync is enabled, busy times are automatically blocked
const schedule = await client.calendar.schedules.create({
  name: 'Work Hours',
  timezone: 'America/New_York',
  availability: [...],
  blockWhenBusy: true, // Block when connected calendars show busy
});

Busy Times

Query busy times (from connected calendars):

const busyTimes = await client.calendar.availability.getBusyTimes({
  userId: 'user_xxx',
  startDate: '2024-01-15',
  endDate: '2024-01-22',
});
 
for (const busy of busyTimes) {
  console.log(`${busy.start} - ${busy.end}: ${busy.title || 'Busy'}`);
}

Real-time Availability

For live booking experiences, use the availability endpoint with short date ranges:

// Check availability for a single day
const todaySlots = await client.calendar.availability.get({
  eventTypeId: 'evt_xxx',
  startDate: '2024-01-15',
  endDate: '2024-01-15',
});
 
// Refresh periodically or on user interaction
setInterval(async () => {
  const updated = await client.calendar.availability.get({
    eventTypeId: 'evt_xxx',
    startDate: selectedDate,
    endDate: selectedDate,
  });
  updateUI(updated);
}, 30000); // Refresh every 30 seconds

Schedule Templates

// Apply common schedule patterns
const schedule = await client.calendar.schedules.createFromTemplate({
  template: 'BUSINESS_HOURS', // 9-5 weekdays
  timezone: 'America/New_York',
  name: 'Standard Hours',
});
 
// Available templates:
// - BUSINESS_HOURS: 9am-5pm Mon-Fri
// - EXTENDED_HOURS: 8am-8pm Mon-Fri
// - WEEKENDS_ONLY: 10am-4pm Sat-Sun
// - 24_7: 24 hours, 7 days

Managing Schedules

List Schedules

const schedules = await client.calendar.schedules.list();
 
for (const schedule of schedules) {
  console.log(`${schedule.name} (${schedule.timezone})`);
  if (schedule.isDefault) {
    console.log('  ^ Default schedule');
  }
}

Update Schedule

await client.calendar.schedules.update(schedule.id, {
  name: 'Updated Name',
  availability: [
    { day: 'MONDAY', startTime: '08:00', endTime: '16:00' },
    // ...
  ],
});

Delete Schedule

await client.calendar.schedules.delete(schedule.id);

Next Steps

Bookings - Handle reservations
Integrations - Connect external calendars
Team Scheduling - Multi-host events