Calendar Scheduling

Calendar scheduling — booking surface + calendar sync, shipped together

Scheduling is always two halves bolted together: a booking surface (an external person reserves a slot — embed, atom, or API call) and calendar sync (you read free/busy to compute availability and write the confirmed event back). Ship one without the other and you get the three bugs the rest of this skill exists to prevent: double-booking, timezone drift after a DST change, and orphaned events on reschedule.

Decide the altitude first

Pick the lowest-code option that still owns the data model you actually need.

Why per row: the embed is zero-maintenance but a black box; the atom/API buys your own UI without owning sync; raw provider is full control and full liability; a unified API trades a vendor for not maintaining three calendar integrations. Hosting, auth/scopes, webhook events, cross-domain support and when each wins, per provider: references/provider-matrix.md.

• Cal.com is open-source and self-hostable. Self-hosted instances get unlimited API access (no cloud rate limit) and full white-label by pointing the embed script at your own domain. REST base is https://api.cal.com/v2.
• Calendly v1 API and its webhooks were discontinued in May 2025. Use v2 (REST/JSON, OAuth 2.1 or personal access token). Do not write new v1 code.

OAuth scopes — narrowest that works

The default mistake is requesting the broad scope "to be safe." On Google, both calendar and calendar.events are restricted scopes — they force a third-party security assessment before you can ship to production. Avoid them when a granular scope does the job.

// Bad — restricted scope, blocks production until a security assessment.
const SCOPES = ["https://www.googleapis.com/auth/calendar"];

// Good — granular ladder, no restricted tier for the common booking case.
const SCOPES = [
  "https://www.googleapis.com/auth/calendar.app.created", // app-owned secondary calendar it creates
  "https://www.googleapis.com/auth/calendar.freebusy",    // your own availability
  // add only if you must read the user's existing events to compute slots:
  "https://www.googleapis.com/auth/calendar.events.owned", // manage only events your app created
  "https://www.googleapis.com/auth/calendar.events.freebusy", // others' busy blocks
];

Scope ladder, narrowest first:

• calendar.app.created — a dedicated secondary calendar your app creates and owns. Best dodge for the restricted assessment when you only need your events.
• calendar.freebusy / calendar.events.freebusy — read availability (own / others') without reading event contents.
• calendar.readonly / calendar.events.readonly — read paths only.
• calendar.events.owned — write, but only events your app created.
• calendar / calendar.events — restricted; request only if you genuinely manage arbitrary events the app didn't create.

Availability without double-booking — the core flow

Both classic races (computing slots in the browser, and writing the event before re-checking) are eliminated by doing this server-side, in order:

1. freebusy.query across every relevant calendar (the host's, plus any secondary calendars that block time). Never trust a cached availability blob.
2. Compute slots server-side applying buffers (gap before/after), minimum notice (no "book in 5 minutes"), working hours, and slot length. The browser may render slots; it must never decide them.
3. Place a short-lived hold/lock on the chosen slot (a row with a TTL, or a tentative event) so a second request in the same window collides on the lock, not on the calendar.
4. Write the event LAST — only after the lock is held.
5. Re-check freebusy inside the write transaction. If the slot went busy between step 1 and now, abort and re-offer. This is the line that actually prevents the double-book.

Decision — do you need a hold step?

Google's availability primitive is freebusy.query (POST, returns busy blocks per calendar); the write is events.insert. Both payloads (with conferenceData for Meet), watch channels + sync tokens, recurring-event edge cases and refresh-token handling: references/google-calendar-sync.md.

Timezone correctness

DST is where naive scheduling code dies. Rules:

• Store the instant in UTC and carry the IANA zone id (e.g. Europe/Andorra) separately. Never store a bare wall-clock string.
• Render in the invitee's zone, derived from the IANA id — not from a browser UTC offset. An offset (+02:00) is correct only on the day it was captured; it silently breaks across a DST boundary.
• Google event payloads MUST set timeZone alongside dateTime, or Google interprets the time in the calendar's default zone and the meeting drifts.

// Bad — floating wall-clock, no zone. Drifts after the clocks change.
{ "start": { "dateTime": "2026-10-25T10:00:00" } }

// Good — instant + explicit IANA zone on both ends.
{
  "start": { "dateTime": "2026-10-25T10:00:00", "timeZone": "Europe/Andorra" },
  "end":   { "dateTime": "2026-10-25T10:30:00", "timeZone": "Europe/Andorra" }
}