Need booking API for SaaS with Google Calendar sync

Here’s a solid booking API design for a SaaS product with Google Calendar sync.

Core requirements

Your API should support:

• multi-tenant SaaS accounts
• staff/resources with calendars
• availability lookup
• create/update/cancel bookings
• Google Calendar 2-way sync
• webhooks/events for external integrations
• timezone-safe scheduling

---

Suggested architecture

Main services

1. Booking Service

   • Owns booking records, availability, conflict checks
   • Exposes REST/GraphQL API

2. Calendar Sync Service

   • Handles Google OAuth
   • Manages Google Calendar API calls
   • Syncs booking ↔ Google events
   • Processes push notifications / webhooks

3. Job Queue / Worker

   • Retries sync failures
   • Polls incremental sync tokens
   • Reconciles data drift

4. Database

   • Tenants, users, staff/resources, booking rules, bookings, sync state

---

Data model essentials

Tenant

• id
• name
• timezone
• plan
• created_at

User / Staff

• id
• tenant_id
• name
• email
• role
• google_account_id nullable

Calendar connection

• id
• tenant_id
• user_id or resource_id
• provider = google
• access_token encrypted
• refresh_token encrypted
• expiry_at
• google_calendar_id
• sync_token
• status

Booking

• id
• tenant_id
• customer_name
• customer_email
• resource_id
• start_at
• end_at
• timezone
• status = confirmed|cancelled|pending
• external_event_id
• source = api|widget|google
• created_at

Availability rules

• working hours
• buffers
• holidays
• exceptions
• slot duration

---

API endpoints

Auth / tenant

• POST /v1/auth/login
• GET /v1/me
• GET /v1/tenants/{tenantId}

Booking

• GET /v1/availability?resource_id=&date=
• POST /v1/bookings
• GET /v1/bookings/{id}
• PATCH /v1/bookings/{id}
• DELETE /v1/bookings/{id}

Calendar sync

• GET /v1/integrations/google/connect
• GET /v1/integrations/google/callback
• POST /v1/integrations/google/disconnect
• GET /v1/integrations/google/status
• POST /v1/webhooks/google/calendar

Admin / ops

• POST /v1/bookings/{id}/sync
• POST /v1/integrations/google/reconcile

---

Example booking flow

1) Check availability

Client asks:

GET /v1/availability?resource_id=123&date=2026-10-20

API returns open slots after:

• working hours
• existing bookings
• Google Calendar busy events
• buffers
• holidays

2) Create booking

POST /v1/bookings
Content-Type: application/json

{
  "resource_id": "123",
  "customer_name": "Jane Doe",
  "customer_email": "jane@example.com",
  "start_at": "2026-10-20T10:00:00-04:00",
  "end_at": "2026-10-20T10:30:00-04:00",
  "timezone": "America/New_York"
}

3) Persist + sync

• Save booking locally first
• Create Google Calendar event
• Store external_event_id
• Mark sync status synced or pending_retry

---

Google Calendar integration approach

OAuth

Use OAuth 2.0 with offline access:

• request access_type=offline
• store refresh token securely
• refresh tokens when access expires

Sync directions

A. Push booking → Google

When booking created/updated/cancelled:

• create/update/delete corresponding Google event

B. Google → booking

If staff edits Google event:

• use Google Calendar push notifications + incremental sync
• update your booking record if allowed
• or mark conflict/manual review

---

Important sync rules

1) Source of truth

Decide this upfront:

• Option A: SaaS is source of truth, Google is downstream mirror
• Option B: Google edits can modify booking
• Option C: Hybrid with conflict resolution

For most SaaS booking systems, I recommend:

• SaaS is source of truth
• Google events can block availability
• Google edits on synced events are read/merge only if explicitly allowed

2) Idempotency

Use idempotency keys on booking creation:

• prevents duplicate bookings if client retries

3) Conflict handling

Before confirming:

• recheck availability
• lock slot briefly in transaction
• ensure Google event creation doesn’t double-book

4) Timezones

Store:

• UTC timestamps
• original timezone
• display timezone

5) Retry strategy

If Google API fails:

• booking can still be created with sync_status=pending
• retry in background
• notify if permanent failure

---

Webhook handling

Google push notifications

Google Calendar API uses channel notifications:

• receive webhook
• fetch incremental changes using sync token
• update local busy blocks/bookings

Your own webhooks

Expose events for customers:

• booking.created
• booking.updated
• booking.cancelled
• calendar.synced
• calendar.sync_failed

---

Security considerations

• Encrypt Google tokens at rest
• Use short-lived access tokens, rotate refresh token handling
• Verify webhook signatures where applicable
• Use per-tenant authorization checks
• Limit scopes to minimum needed:
  • usually https://www.googleapis.com/auth/calendar.events
  • or read-only calendar.readonly if only checking availability

---

Suggested minimal tech stack

• API: Node.js/NestJS, Go, or Python/FastAPI
• DB: PostgreSQL
• Queue: Redis + BullMQ / Celery / SQS
• OAuth + Google API: official Google client libraries
• Webhook processing: background workers
• Cache: Redis for slot availability

---

If you want a practical starting point

I can generate any of these next:

1. OpenAPI spec for the booking + Google sync API
2. Database schema for PostgreSQL
3. Node.js/NestJS implementation
4. FastAPI implementation
5. Google Calendar sync flow diagram
6. Multi-tenant SaaS architecture

If you want, I can draft the full OpenAPI 3.0 spec next.