Cloudbeds

Cloudbeds

Property management for hotels and vacation rentals. One connected account can span many properties under an organization.

Hierarchy

Organization → Properties (propertyID) → Room types → Physical rooms → Reservations → Guests → Folio lines.

Channel bookings (Airbnb, Expedia, website, etc.) land as reservations with sourceName and sourceID. Airbnb-synced stays appear as sources like Airbnb (API) — there is no separate Airbnb API in this bundle.

Operational order

1. Discover scope — enumerate properties, then pick a propertyID for all property-scoped reads.
2. Daily pulse — dashboard snapshot for occupancy, arrivals, departures, and in-house counts.
3. Channel triage — list booking sources at the property, then filter reservations by sourceID (not sourceName).
4. Stay lookup — reservation lists with date/status filters; single-booking detail or folio invoice when you have reservationID.
5. Availability & rates — room-type availability for a stay window (counts + quoted rates), or rate-plan calendar across a date range. Use the rate-detail reservation list when you need per-night lines on existing bookings.
6. Guest & folio — guest profiles, folio transactions, and recorded payments scoped to a reservation.

What this bundle covers

Write operations

All writes use form-encoded bodies. Nested arrays (rooms on create, rate intervals) pass as structured list parameters — use extra_fields for rarely used upstream keys.

High-impact writes (real folio or PMS rows): reservation create, payment record, item post, rate update, check-in/out. Confirm intent before calling.

Token scopes: Writes need matching write:* scopes on the API key. Read-only tokens fail with permission errors.

Not available via Cloudbeds API

• Guest messaging (Airbnb/OTA inbox) — not exposed.
• Listing reviews or ranking metrics — channel marketing data stays on the OTA.
• Native Airbnb API — partner-gated; synced reservations are the supported path.

Gotchas

• Always scope by property: Unscoped reservation lists can return tens of thousands of rows.
• Resolve property from reservation id: Call get_reservations with reservation_id only — the list row includes propertyID. Do not guess property_id on single-booking detail; wrong pairs return "Invalid Reservation".
• Single-booking detail needs the owning property: On multi-property accounts, pass property_id from the list row, or use reservation-only list lookup first.
• Source filter casing: Filter reservations with source_id (matches upstream sourceID), not alternate spellings from docs.
• Rate plans need both dates: start_date and end_date are required.
• Payment lists need a scope: Pass reservation_id, guest_id, or house_account_id — property alone is not enough. guest_id is usually fastest; reservation-scoped ledger reads can take 30–75 seconds.
• Transaction lists are slow without reservation_id: Property-wide folio history can exceed 60 seconds — always pass reservation_id from a reservation list when you have it.
• Physical rooms are nested upstream: get_rooms returns a flat rooms array plus physical_room_count in addition to the raw property blocks.
• Pagination: Default page size is modest; filter before paging deep into large accounts.
• Guest search: get_guests filters by exact guest_email or guest_phone; name-only filters are weak — prefer email/phone when finding past stays.
• Communications & door codes: Property must have those Cloudbeds features enabled; otherwise reads may return not found.
• Data insights: Aggregated reports need Insights enabled on the Cloudbeds account; use get_data_insights with a date range and report type.