Design Airbnb

Assume 4.5 million active listings, 150 million nights booked a year and an average stay of just under four nights. Guests search many times for every booking, mostly in the evenings of their home time zone and heavily in January and early summer.

The calendar database is the source of truth for whether a night is free. Only two writers touch it: the booking service and the host calendar path (including iCal sync). Everything else reads it or reads a copy derived from it.

Search never queries the calendar directly. Each listing's document in the search index carries a 365-bit availability bitmap and per-night price bands. When the calendar changes, the booking service emits an event and the indexer patches that one document within a few seconds. A date-range filter becomes a bitwise check: are all bits between check-in and check-out set? That check is cheap enough to run on tens of thousands of candidates per query.

Prices shown in search are estimates. The quote service recomputes the exact total from the calendar's per-night prices, fees and taxes when the guest opens checkout, signs it and gives it a short expiry. The booking call carries that quote id, so the price the guest agreed to is exactly the price charged, even if the host edits prices a minute later.

All of a listing's nights, holds and bookings live on the same partition, chosen by listing id. A booking transaction therefore never spans partitions, which is what keeps it short and safe. Guest-facing views such as "my trips" read from a separate index keyed by guest id that is fed by booking events.

Store one row per listing per night: (listing_id, night, state, booking_id, price), with state one of free, blocked, held or booked. A stay is a set of consecutive rows. To take a stay, a transaction locks those rows with SELECT ... FOR UPDATE in night order and checks that every one is free. Locking in a fixed order means two overlapping attempts cannot deadlock; the second simply waits, then sees the nights are taken.

An alternative is one row per booking with a date range and a Postgres exclusion constraint: EXCLUDE USING gist (listing_id WITH =, stay WITH &&). The database itself rejects any overlapping range, which is elegant and hard to get wrong. Per-night rows win when prices, minimum stays and blocks also vary by night, which they do here, so the per-night table is the main store and the constraint can guard the bookings table as a second line of defence.

Never hold a database transaction open while calling a payment provider. Their p99 can be several seconds, and a lock held that long would block every other guest looking at that listing. Instead, split the work into three short transactions around one external call. First, mark the nights held with an expiry and commit. Then authorise the card. Then flip held to booked and commit again.

Each step is recorded in a booking_attempts row keyed by the idempotency key, so a retry from the client or a restarted worker resumes at the right step instead of starting over. Authorisation uses the same key with the payment provider, so a retried call never creates a second charge. A sweeper releases any hold whose expiry has passed, which covers the case where the booking service dies between steps. If the sweeper finds an authorisation with no confirmed booking, it voids it.

Capture the money later. Authorise at booking, capture around check-in, and pay the host a day after check-in. That ordering makes cancellations cheap: before capture, a cancellation is a void rather than a refund.

A quote is a small pipeline. Read the nightly price for each night of the stay from the calendar rows, apply any weekly or monthly discount the host set, add the cleaning fee once, compute the guest service fee as a percentage of the subtotal, then add occupancy taxes, which depend on the listing's address and sometimes on the number of nights. Currency conversion happens last, at a rate fixed for the life of the quote.

Keep every rule versioned and record which version produced each quote. When a city changes its tourist tax on the first of the month, quotes issued the day before must still be honoured, and support needs to explain the exact numbers a guest saw. Store the full breakdown on the booking row, not just the total, so refunds under a partial cancellation can be computed from the same lines.

When the host must approve, hold the nights for up to 24 hours instead of 10 minutes and authorise the card at request time. Other guests see those dates as unavailable. If the host declines or the window lapses, the sweeper releases the nights and voids the authorisation. Long holds are a trade-off: they protect the guest who asked first but can block a listing for a day, so cap how many pending requests one guest can have open.

Search can show a listing whose last free night was booked two seconds ago. That is acceptable if the listing page and the quote both read the calendar directly and the booking transaction is the final check. What is not acceptable is search being stale by hours. Track indexer lag as a first-class metric, and when it grows, fall back to a quick calendar check on the top results before returning them.