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
- Discover scope — enumerate properties, then pick a propertyID for all property-scoped reads.
- Daily pulse — dashboard snapshot for occupancy, arrivals, departures, and in-house counts.
- Channel triage — list booking sources at the property, then filter reservations by sourceID (not sourceName).
- Stay lookup — reservation lists with date/status filters; single-booking detail or folio invoice when you have reservationID.
- 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.
- Guest & folio — guest profiles, folio transactions, and recorded payments scoped to a reservation.
What this bundle covers
| Need | API surface |
|---|
| Multi-property portfolio | Property list + per-property detail |
| Today's ops | Dashboard occupancy and arrival counts |
| OTA / direct bookings | Reservations + source channel list |
| Airbnb / Expedia visibility | Filter reservations by channel sourceID |
| Availability search | Room types with roomsAvailable for a date range |
| Rate calendar | Nightly rate plans across dates |
| Per-booking revenue detail | Reservations with room rate breakdowns |
| Folio / invoice | Room charges, adjustments, payments on one reservation |
| Inventory | Room types, physical rooms, blocks, housekeeping status |
| POS extras | Property item catalog (sku, price) |
Write operations
All writes use application/x-www-form-urlencoded bodies. Nested arrays (rooms on create, rate intervals) pass as structured list parameters — use extra_fields for rarely used upstream keys.
| Area | Capabilities |
|---|
| Reservations | Create/update bookings, notes, documents, room assign, check-in/out |
| Guests | Add/update profiles, notes, documents, assign to rooms |
| Folio | Post items, adjustments, payments, void lines |
| Rates | Queue nightly rate updates (putRate is asynchronous) |
| Inventory | Room blocks, housekeeping status and assignments |
| Groups & accounts | Group profiles, house accounts, webhooks |
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.
- Single-record reads need propertyID: Guest and reservation detail endpoints reject calls without it.
- Source filter casing: Live API expects sourceID (capital ID), not the sourceId spelling in some docs.
- Rate plans need both dates: startDate and endDate are required.
- Payment lists need a scope: Pass reservationID, guestID, or houseAccountID — property alone is not enough. guestID is the fastest filter; reservationID ledger reads can take 30–75 seconds.
- Transaction lists are slow without reservationID: Property-wide folio history can exceed 60 seconds — always pass reservationID 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.
