Design Airbnb Reservation System

Introduction

Marketplace booking is a distributed systems problem wearing a CRUD costume. The invariant is sharp: no two confirmed reservations may claim the same listing for overlapping nights. Search, pricing, and host dashboards are downstream of that truth—if you get the invariant wrong, every pretty UI is debt.

Interviewers dock “we check availability then insert” without a transaction. They reward night-level inventory (or equivalent), hold TTL, payment saga, and honest stale search versus strong checkout.

How to approach

Draw the state machine: draft → held → payment_pending → confirmed (plus cancelled, expired_hold). Walk one race: two POSTs for the same nights—only one commits. Then hold expiry and authorize/capture. Search indexing last or simplified.

Interview tips

• Time zones: anchor nights in listing-local time—not UTC hand-waving—minimum stay and DST boundaries bite.
• Idempotency: double-click and mobile retries need Idempotency-Key on reserve—same key returns the same reservation id.
• Search vs truth: discovery can show stale “available”; checkout must re-read authoritative rows; 409 if the user lost the race.
• Host approval: extra pending_host state—inventory may still need a soft hold; state the machine clearly.
• Outbox: after confirm, emit events (email, calendar, analytics) reliably—not only inline.

Capacity estimation

Concern	Angle
Hot listing	Contention on one listing’s nights—queue or optimistic UX (“someone else booked—refresh”)
Read vs write	Search is read-heavy; checkout is write-light but must be exact
Index	Availability index for range queries, updated on confirm/cancel—lag OK for browsing, not for paying

Implications: serialize conflicts at the listing calendar shard; do not rely on scanning globally “locked” rows for search.

High-level architecture

The listing / calendar service owns authoritative night rows (or an interval tree) per listing, sharded by listing_id. The booking orchestrator implements a saga: create hold → payments authorize → capture → confirm reservation; on failure compensate (release hold, void auth). Search / discovery reads a replica or index—eventually consistent. Notification workers consume outbox events.

Who owns what:

• Calendar service — invariant enforcement; transactions on night rows.
• Payments adapter — PCI boundary; idempotent charges.
• Booking API — orchestration, timeouts, human-readable errors.
• Search indexer — denormalized availability for filters—not source of truth.

[ Guest ] --> [ Booking API ]
                  |
        +---------+---------+
        |                   |
   [ Calendar svc ]    [ Payments ]
   (ACID per listing)   (authorize/capture)
        |
        | confirm: mark nights RESERVED
        v
   [ Reservation DB ] ----outbox----> [ Email / calendar / search indexer ]

In the room: Narrate the synchronous path for confirm (few RTTs) versus async side effects—never block confirm on SMTP.

Core design approaches

Night inventory table

Each row (listing_id, night_date) is available | held | booked. A uniqueness constraint prevents double booking. Holds use held_until.

Interval / exclusion

Postgres exclusion constraints on tstzrange are powerful; many interviews stay at simpler night granularity.

Viral listing funnel

Optimistic: many short-TTL holds; first capture wins; others get 409. Queue: serialize checkout attempts—fairness tradeoff.

Detailed design

Write path (reserve)

1. BEGIN; lock listing calendar rows for the date range (or SELECT … FOR UPDATE on nights).
2. Verify all nights available; insert hold rows with held_until = now + 15m.
3. COMMIT; return reservation_id and client secret for payment.
4. Authorize payment asynchronously; on success BEGIN capture transaction: mark booked, clear hold, emit event.

Read path (availability)

GET availability reads nights or cache for speed; checkout re-runs the same check inside the booking transaction.

Key challenges

• Phantom reads: availability checked outside the txn then booked inside—lost update. Fix: the transaction boundary includes the read.
• Payment vs hold mismatch: auth expires before capture—reconciliation voids or re-auth—the state machine must cover the edge.
• Modification: changing dates means release old + acquire new—two-phase risk—saga or single txn if same listing.
• Search index lag: user sees available then fails checkout—UX copy must explain the race.

Scaling the system

• Shard calendar by listing_id—hot listing is one shard hotspot; acceptable if transactions stay short; mitigate with queue or optimistic UX.
• Read replicas for browsing; primary for booking transactions.
• Cache availability per listing with short TTL; invalidate on write.

Failure handling

Failure	Mitigation
Payment down	Hold expires; user retries; no charge
DB failover during txn	Idempotent retry; reconcile orphan holds
Worker crash after auth before capture	Reconciliation job completes or voids
Double submit	Idempotency key maps to same reservation

Degraded UX: occasional 409 on a hot listing; outage is wrong double-booking—that is unacceptable.

API design

GET  /v1/listings/{id}/availability?from=YYYY-MM-DD&to=YYYY-MM-DD
POST /v1/reservations
POST /v1/reservations/{id}/confirm
POST /v1/reservations/{id}/cancel

POST /v1/reservations

Field	Role
listing_id	Target
check_in, check_out	Half-open range [check_in, check_out)—state clearly
guest_count	Policy
idempotency_key	Dedup retries

GET /v1/listings/{id}/availability

Param	Role
from, to	Range in listing-local dates
expand	Optional pricing components

Diagram:

GET availability (may be slightly stale index)
       |
       v
POST /reservations --> [ txn: lock nights + hold ] --> 201 + payment_client_secret
       |
       v
POST /payments/authorize (PCI boundary)
       |
       v
POST /reservations/{id}/confirm --> [ txn: capture + booked ]

Errors: 409 conflict; 410 hold expired; 402 payment failed.

Production angles

Marketplace reservations sit on the knife-edge between search (eventually consistent indices) and checkout (serializable truth about nights). The expensive incidents are ghost holds, double books, and money in limbo—not 409 rates during a viral listing, which can be healthy competition if the product story is clear.

Spike in 409 on a viral property — race vs bug

What it looks like — Support and social channels light up on a trending stay; metrics show 409 rate up on POST /reservations. Product asks if the site is broken; engineering asks if inventory math is wrong.

Why it happens — Organic contention—many users racing for finite nights—produces 409 by design when only one transaction wins. Bad 409s come from split brains between cache, search index, and authoritative rows—different shape on dashboards (retry storms vs flat failure rate with weird state transitions).

What good teams do — Optimistic UI that refreshes availability after conflict; optional fair queue or waitlist for drops—product policy; metrics for conflict_after_index_said_available vs simple race. Seniors separate expected business contention from correctness bugs.

Ghost holds block the calendar — nobody paid, nobody can book

What it looks like — Calendar blocked for hours with no completed booking; hosts complain; finance sees authorized cards with no matching reservation row, or orphan holds past held_until.

Why it happens — Worker crashed after auth but before commit or release; saga lost the compensating action; client closed mid-flow. Payment idempotency does not automatically release inventory rows.

What good teams do — Sweeper jobs for held_until < now() with metrics on hold age distribution; alert when p95 hold duration exceeds the product promise; reconciliation between payment intent, reservation state, and availability locks—hourly if not continuous.

Payment authorized but capture delayed — two SLOs, one user journey

What it looks like — Bank shows pending charge; app shows “processing”; user books elsewhere thinking this one failed. Support refunds pile up.

Why it happens — Auth succeeds at issuer; capture delayed by partition, retries, or fraud holds; inventory lock TTL does not match issuer behavior.

What good teams do — Reconciliation ledger linking payment_intent, reservation_id, and capture events; void stale auths with documented SLA to finance; separate SLOs for inventory correctness vs payment settlement, and a customer-visible timeout after which holds release deterministically.

How to use this in an interview — Lead with search index staleness vs checkout truth: always re-check live inventory inside the booking transaction—search results are hints, not locks. Name one sweeper or reconciliation story for ghost holds.

Bottlenecks and tradeoffs

• Search freshness vs booking truth: index can lag; checkout must hit authoritative inventory—honest UX and metrics on stale conflict rate.
• Hold duration vs conversion: long holds reduce double-book risk but anger hosts; short holds increase 409s—tune with experiments.
• Global vs local inventory: sharding by listing is natural; cross-listing packages and multi-night atomicity complicate transactions—scope honestly.