CloudBeds Integration

Connects via a direct API key. No OAuth flow. One key covers all properties registered under the same Cloudbeds account. CloudBeds official site ↗

Supported features

Feature	Supported	Notes
Hotel availability	✓	Room types, dates, occupancy, with the property's stay rules for those dates
Stay restrictions	✓	Minimum and maximum stay, closed to arrival or departure — explained before booking
Room types	✓
Room rates	✓
Create reservation	✓	Two-step flow; explicit guest confirmation required; refused when the stay breaks a stay rule
List / get reservations	—
Rate plans	—	Used internally only
Payment link	—

Setup steps

Get your API key from Cloudbeds
Log in to the Cloudbeds Marketplace (Apps & Marketplace → API section). Generate an API key scoped to the property you are connecting. Copy the key immediately — it is shown only once.
If you manage multiple Cloudbeds properties, each shares the same API key but needs its own entry in the hotelConfig array.
Find your property ID(s)
In Cloudbeds, navigate to Settings → Property. The property ID is the numeric identifier shown in the URL (/property/12345). You need one entry per property in hotelConfig.
3
Enter the credentials in the business console
Open the business console, select your client, and go to PMS Integration. Choose CloudBeds as the provider and fill in:
- apiKey — paste the key from step 1
- hotelConfig — one entry per property: id (property ID from step 2) and name (display name)
Enable the integration
Toggle Active to on and save. The agent will immediately begin using live CloudBeds data. To enable the agent to create reservations on behalf of guests, also toggle Enable Reservation Creation.

If you need to update your Cloudbeds API key or apply new Maison features to your property, you must uninstall and reinstall the Maison app in the Cloudbeds Marketplace. Updating credentials in the console alone is not sufficient — a fresh installation ensures all feature permissions are re-granted correctly.

Available tools

10 tools are available for CloudBeds. The concierge calls them on a guest's behalf during a conversation; which are enabled is set per property, so you only turn on what you want it to be able to do.

Enabled by default (3)

On as soon as the integration is connected, with nothing else to configure.

Tool	What it does
`cloudbeds_get_availability`	Check which room types are available and their nightly rates for specific dates. Use this when a guest asks 'do you have rooms for...', 'what's available for...', 'can I book a room from... to...', or any general availability question. startDate = check-in date, endDate = check-out date, both in YYYY-MM-DD format (e.g. 2026-09-01). Set children=0 when there are no children. Returns available room types with nightly rates and availability count, plus the property's length-of-stay rules for the stay, PER ROOM TYPE and rate plan (`roomTypeRestrictions`): a room type is bookable when at least one of its rate plans allows the stay. `restrictionSummary` says which room types cannot be booked as asked (minimum or maximum stay, closed to arrival or departure), which rate plans still allow it, and for a too-short stay the earliest check-out that works — tell the guest this proactively, never let them discover it at booking. `blocked` is true only when no room type can be booked. `restrictionsChecked` false means the rules could not be read; say the stay is subject to the property's minimum-stay rules. An empty data array means no rooms are available for those dates — not an error.
`cloudbeds_get_rate_plans`	Retrieve available rate plans and pricing for the given date range. Use this to answer questions about pricing details, rate plan names, or stay restrictions. Set detailedRates=true to see per-night rates and min/max length-of-stay restrictions (minLos, maxLos, closedToArrival, closedToDeparture) — essential when a guest asks why a specific date range cannot be booked or when the availability tool returns no results. startDate and endDate are required, in YYYY-MM-DD format. Optionally filter by roomTypeID to get rates for a specific room type.
`cloudbeds_get_room_types`	Retrieve the hotel's room type catalog with descriptions and occupancy details. Use this to answer 'what types of rooms do you have?', 'describe your rooms', or when a guest wants to compare room options before asking about specific dates. All parameters are optional. Rates are only returned when all of startDate, endDate, adults, and children are provided — omit them if the guest only wants general room information. Dates must be in YYYY-MM-DD format.

Available on request (7)

Off by default. Ask Maison to enable any of these for your property — several change data in your CloudBeds account, so they are opt-in rather than assumed.

Tool	What it does
`cloudbeds_create_reservation`	Create a NEW reservation (booking) for a guest. The property's length-of-stay rules are checked first for the rooms and rates being booked: if the stay breaks a minimum or maximum stay or a closed-to-arrival/departure date on the chosen rate, the call is refused with the reason — relay it and offer the earliest check-out or the rate plan that works. Always pass roomRateID when the guest chose a rate plan. BEFORE calling: confirm every detail with the guest — room type, check-in and check-out dates (ISO YYYY-MM-DD), number of adults and children, guest name, country, and postal code — and get their explicit go-ahead. Maison's standard flow: after creating, immediately call cloudbeds_update_reservation with status='not_confirmed' to hold the booking as pending/unpaid. Never retry creation after a timeout — the booking may already exist and retrying can double-book the guest; look it up with cloudbeds_get_reservations instead. rooms, adults, and children are parallel arrays keyed by roomTypeID (get IDs from cloudbeds_get_availability); supply a children entry for EVERY room type, with quantity 0 when there are no children. On success returns the reservationID and grand total — always relay both to the guest.
`cloudbeds_get_app_state`	Check the Cloudbeds integration's connection status for the property. Returns the app state: enabled, disabled, installing, or pending. Use this to diagnose whether the Cloudbeds connection is working when other tools fail. Takes no parameters. Not useful for guest questions.
`cloudbeds_get_available_room_types`	Raw room availability and nightly rates for specific dates, WITHOUT the property's length-of-stay rules — prefer cloudbeds_get_availability, which includes them. startDate = check-in date, endDate = check-out date, both in YYYY-MM-DD format. Set children=0 when there are no children. An empty data array means no rooms are available for those dates — not an error.
`cloudbeds_get_rate`	Get the rate quote for ONE specific room type over a date range. Use this only when the guest has already chosen a room type and you know its roomTypeID — for general 'what's available' or price-comparison questions prefer the availability tool instead. startDate = check-in, endDate = check-out, both in ISO YYYY-MM-DD format. Set detailedRates=true to get a per-night breakdown with rooms available and stay restrictions (minLos, maxLos, closedToArrival, closedToDeparture) — useful to explain why a stay cannot be booked. Only non-derived rates are quoted; the returned totalRate includes extra-guest charges.
`cloudbeds_get_reservation_details`	Look up one reservation by its reservation ID and return its status, stay dates, main guest name, totals, balance owed, and assigned rooms. Use this when a guest asks about their existing booking ('what's my reservation?', 'when do I check in?', 'what do I still owe?'), and before any room-level change with cloudbeds_update_reservation. Requires the exact reservationID — find it first with cloudbeds_get_reservations if the guest only knows their name or dates. Dates are ISO YYYY-MM-DD.
`cloudbeds_get_stay_restrictions`	The property's length-of-stay rules for one stay, per room type and rate plan: which room types can be booked as asked, on which rate plans, why the others cannot (minimum or maximum stay, closed to arrival or departure), the earliest check-out that satisfies a minimum, and the per-night rows behind it. cloudbeds_get_availability already includes this; call it directly when a guest asks why a stay cannot be booked or how long they must stay. startDate = check-in, endDate = check-out, YYYY-MM-DD. Pass `rooms` (the room types and roomRateIDs about to be booked) to get a verdict for exactly that booking.
`cloudbeds_update_reservation`	Update an existing reservation: change its status, estimated arrival time, checkout date, or room configuration (dates, occupancy, room type per room). Status values: 'not_confirmed' = pending/on hold (Maison's standard state right after cloudbeds_create_reservation, until payment is confirmed), 'confirmed' (set after payment), 'canceled' (cancels the booking), 'checked_in', 'checked_out', 'no_show'. Changing ONLY the checkout date: send the top-level checkoutDate parameter. ANY room-level change (check-in date, adults, children, room type, rate): first call cloudbeds_get_reservation_details, then resend the COMPLETE rooms array with every room's checkinDate and checkoutDate — partial room updates are not possible. Confirm the exact change with the guest before calling — cancellation and date changes are hard to undo and may carry penalties per the property's policy. Dates are ISO YYYY-MM-DD; estimatedArrivalTime is 24-hour HH:MM. To change assigned physical rooms use cloudbeds_post_room_assign instead.

Not yet certified (68)

Built and working against the CloudBeds API, but Maison is not yet certified with CloudBeds to use them in production, so they cannot be enabled today. Listed so you can see what is coming rather than discover the gap when you ask for it.

Tool	What it does
`cloudbeds_append_custom_item`	OPERATOR-GRADE: posts charges to a folio — never use in guest conversations unless explicitly instructed. Append one or more custom items (and optional payments) to an EXISTING custom-item transaction on a reservation, house account, or group folio — use cloudbeds_post_custom_item to start a new transaction. referenceID is required and identifies the partner transaction to append to (it also prevents duplicates). Provide exactly one of reservationID, houseAccountID, or groupCode. NEVER auto-retry blindly after a timeout — re-send only with the SAME referenceID so the dedup guard applies, or verify the folio state first.
`cloudbeds_create_allotment_block_note`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Add a free-text note to an allotment block (e.g. contract terms, pickup review reminders). allotmentBlockCode identifies the block (from the allotment-blocks tool).
`cloudbeds_delete_adjustment`	OPERATOR-GRADE: voids a folio MONEY adjustment — never use in guest conversations unless explicitly instructed. Void an adjustment transaction (by adjustmentID, as returned by cloudbeds_post_adjustment) on the specified reservation. NEVER auto-retry this call after a timeout or ambiguous failure — the adjustment may already be voided; verify the current folio state first.
`cloudbeds_delete_guest_note`	Archive (remove) an existing guest note. Requires the guestID and the noteID (from cloudbeds_get_guest_notes). Use only when a note is confirmed obsolete or was added in error — to change a note's text use cloudbeds_put_guest_note instead.
`cloudbeds_delete_reservation_note`	Archive (delete) an existing reservation note, identified by reservationNoteID (from cloudbeds_get_reservation_notes). Only delete a note when explicitly asked to remove it — prefer cloudbeds_put_reservation_note to correct a note's text.
`cloudbeds_get_allotment_blocks`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. List the property's allotment blocks (held group/event room inventory) with pickup counts (roomsHeld, roomsPickedUp, roomsRemaining), release schedule, and day-by-day interval availability per room type. Filter by allotmentBlockCode, group, event, status, room type, or a date window (ISO YYYY-MM-DD). Use this to answer how many rooms a group block still holds or when a block releases.
`cloudbeds_get_booking_fees_taxes`	Calculate the fees and taxes that apply to a booking quote — designed for showing a guest the full price breakdown at checkout. Provide the stay dates (ISO YYYY-MM-DD), the room total INCLUDING taxes (roomsTotal, from the availability or rate tools), and the number of rooms. Include adultsPerRoom when the property charges per-person taxes. Returns itemized fees, taxes, the rooms total without taxes, and the grand total. For the property's general tax/fee catalog use the taxes-and-fees tool instead.
`cloudbeds_get_currency_settings`	Get the property's currency configuration: default currency ISO code, other acceptable currencies, number formatting (decimal/thousand separators), and any fixed exchange rates configured by the property. Use this to answer 'what currency do you charge in?' or 'do you accept euros/dollars?'. Takes no parameters.
`cloudbeds_get_custom_fields`	List the property's configured custom field definitions (the extra fields shown on reservations, the booking engine, or registration cards): name, shortcode, where each applies (reservation or guest), whether it is required, its input type, and where it is displayed. This is a configuration lookup — it returns field DEFINITIONS only, never guest-entered values. Optionally filter by customFieldID or shortcode.
`cloudbeds_get_dashboard`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Get the property's daily operations summary: rooms occupied, occupancy percentage, expected arrivals (check-ins), expected departures (check-outs), and in-house count. Aggregate numbers only — no guest details. Optionally pass a date in ISO YYYY-MM-DD format; defaults to today.
`cloudbeds_get_email_schedule`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. List the Cloudbeds-NATIVE email schedules configured on the property (schedule ID, name, linked template ID and name, active flag). Visibility only: Maison suppresses native PMS emails and sends its own — schedules cannot be created or edited through this interface. Use the email-templates tool to see the templates themselves. Takes no parameters.
`cloudbeds_get_email_templates`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. List the Cloudbeds-NATIVE email templates configured on the property (ID, name, subject, active flag). Visibility only: Maison suppresses native PMS emails and sends its own — these templates are NOT what guests receive from Maison, and they cannot be created or edited through this interface. Takes no parameters.
`cloudbeds_get_files`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. List the files attached to the hotel profile (documents, images, spreadsheets), newest first: file name, type, source, creation date, and download URL. Optionally filter by name (substring match). Read-only — files cannot be uploaded through this interface.
`cloudbeds_get_group_notes`	Retrieve the free-text notes attached to a group profile. Use this to see special arrangements, billing instructions, or event details recorded against a group booking. groupCode identifies the group (from the groups tool). pageNumber and pageSize are required by the API — use pageNumber 1 and pageSize 100 unless paging through many notes.
`cloudbeds_get_groups`	List the property's group profiles (groups, companies, travel agents) with status, source and organizer contact people. Use this to look up a group booking profile by its groupCode, or to browse open/closed groups. createdFrom/createdTo filter by creation datetime (ISO format). For the free-text notes attached to a group use the group-notes tool; for the group's held room inventory use the allotment-blocks tool.
`cloudbeds_get_guest`	Get the profile of a single guest — name, email and phone number — by guestID or by reservationID (returns the reservation's main guest). Provide exactly one of guestID or reservationID. Use this after verification when you need the booker's own contact details on file. For lists of guests use cloudbeds_get_guests_modified, cloudbeds_get_guests_by_status or cloudbeds_get_guests_by_filter instead.
`cloudbeds_get_guest_notes`	Retrieve the notes on a guest's profile (note text and created/modified timestamps). Use this to check what has already been recorded about a guest before adding a new note with cloudbeds_post_guest_note.
`cloudbeds_get_guests_by_filter`	Find guests by reservationID, roomID, guest name and/or check-in/check-out date ranges (dates in YYYY-MM-DD). status is required: cancelled (note the double-l spelling here), checked_out, in_house or not_checked_in. Use this to answer 'who is staying in room X' or to look up a guest by name. Returns guest name, room assignment and whether they are the main guest — no contact details.
`cloudbeds_get_guests_by_status`	List guests currently in a given status: not_checked_in, in_house, checked_out or canceled (note the single-l spelling here). Sorted by modification date; optionally bound the modification window with resultsFrom/resultsTo (ISO date-times). Use this for questions like 'which guests are in-house right now'. Returns names, room assignments, stay dates and status only — no contact details.
`cloudbeds_get_guests_modified`	List guests with their room assignment and stay dates, filtered by modification date and/or check-in/check-out date ranges. Set inHouse=true to list only guests currently in the hotel. If no date range is given, only records modified today are returned. Dates use ISO YYYY-MM-DD format; resultsFrom/resultsTo accept ISO date-times (e.g. 2026-09-01T00:00:00Z). A guest assigned to multiple rooms appears once per room. Returns names, room assignments and stay dates only — no contact details.
`cloudbeds_get_hotel_details`	Get the hotel's full profile: description, address, phone, email, check-in and check-out times, late check-out policy and charge, terms and conditions, whether full payment is required before check-in, amenities list, currency, and primary language. This is the primary tool for guest questions like 'what time is check-in?', 'do you allow late check-out?', 'what amenities do you have?', 'where are you located?', or 'how can I contact the hotel?'. Takes no parameters — the property is resolved automatically. For a brief list of all properties on the account use the hotels-list tool instead.
`cloudbeds_get_hotels`	List the properties on the Cloudbeds account with a one-line summary each: name, description, and timezone plus currency. Takes no parameters — results are scoped to the connected property. Use the hotel-details tool instead for policies, check-in/out times, amenities, address, and contact details — this list has none of those.
`cloudbeds_get_house_accounts`	List the property's house accounts (ID, name, open/closed status, private flag) — internal billing folios not tied to a reservation. Use this to find a houseAccountID before posting payments or items to a house account. Takes no parameters.
`cloudbeds_get_housekeepers`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. List the property's housekeepers (housekeeperID and name). Use this to look up a housekeeperID before assigning rooms or filtering the housekeeping-status board by housekeeper. For each housekeeper's current room list use the housekeeping-status tool with housekeeperIDs instead.
`cloudbeds_get_housekeeping_status`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Get the current day's housekeeping board: per-room cleaning condition (clean/dirty), occupancy, blocked flag, frontdesk status (check-in, check-out, stayover, turnover, unused), assigned housekeeper, and the do-not-disturb / refused-service / vacant-pickup flags. Use this to answer 'which rooms are dirty?', 'what rooms does housekeeper X have?', or 'which rooms turn over today?'. All filters are optional: roomTypeIDs and housekeeperIDs accept comma-separated IDs (housekeeperIDs=0 returns rooms with no assigned housekeeper). Always reflects the live state — results are never cached.
`cloudbeds_get_item`	Get the full details of ONE sellable item by itemID: price, category, stock levels, and the itemized taxes and fees that apply. Use this when you already know the itemID (from cloudbeds_get_items) and need its exact price breakdown — for browsing the whole catalog use cloudbeds_get_items instead.
`cloudbeds_get_item_categories`	List the hotel's item categories (ID, name, code). Use this to browse the sellable catalog by category or to find an itemCategoryID for filtering cloudbeds_get_items. Takes no parameters.
`cloudbeds_get_items`	List all items (products, services, meal plans) the hotel sells, with prices, categories, stock levels, and tax/fee totals. Use this to answer 'what can I order?', to find an itemID before posting an item to a folio with cloudbeds_post_item, or to check stock. Optionally filter by itemCategoryID (from cloudbeds_get_item_categories). Stock fields (itemQuantity) only appear when the item tracks inventory; tax/fee totals only when taxes or fees are assigned.
`cloudbeds_get_packages`	List the Cloudbeds feature packages active for the property — the platform feature sets the property can use (an operator/configuration lookup, NOT guest-bookable packages or offers). Takes no parameters. Returns the list of active package names.
`cloudbeds_get_payment_methods`	List the property's enabled payment methods (method key, code, display name) and the payment gateway in use with its currency. Use this to discover the valid 'type' values before recording a payment with cloudbeds_post_payment, or to answer 'what payment methods do you accept?'. Takes no parameters.
`cloudbeds_get_payments_capabilities`	List the property's payment processing capabilities: whether Cloudbeds Payments is enabled, whether a card terminal or tap-to-pay is available, the backend gateway in use, and whether Pay-by-Link is enabled. An operator/configuration lookup — for the guest-facing list of accepted payment methods use cloudbeds_get_payment_methods instead. Takes no parameters.
`cloudbeds_get_rate_jobs`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Look up the status of asynchronous rate-update jobs created by the rate-update tools (patch/put rate). Pass the jobReferenceID returned by a rate update to track that specific job; each job reports in_progress, completed, or error, plus the per-interval actions taken. Jobs are only retained for 7 days. Optionally filter by status.
`cloudbeds_get_reservation_assignments`	List which rooms are assigned (and how many are still unassigned) per reservation for one date. Defaults to today when no date is given; date is ISO YYYY-MM-DD. Use this to answer 'which room is reservation X in tonight?' or to review the day's room assignments. For full detail on one assigned room use cloudbeds_get_reservation_room_details.
`cloudbeds_get_reservation_notes`	List all notes on a reservation, with author name and creation/modification timestamps. Use this to check what has already been recorded on a booking before adding or updating a note.
`cloudbeds_get_reservation_room_details`	Get details of one specific room within a reservation by its subReservationID: room name and type, room status (in_house, checked_out, not_checked_in, cancelled), occupancy counts, and the guests assigned to that room. Use this before room-level actions (check-in, check-out, reassignment) or when a multi-room reservation needs per-room information. Get the subReservationID from cloudbeds_get_reservation_assignments or cloudbeds_get_reservation_details.
`cloudbeds_get_reservations`	Search reservations by status, guest name, or check-in/check-out date ranges. Use this to find a guest's reservation ID when they only know their name or stay dates, or to list arrivals/departures for a date window. All dates are ISO YYYY-MM-DD. Returns one summary row per reservation (ID, status, guest name, dates, balance) — use cloudbeds_get_reservation_details for full details of a specific booking. Results are paginated (pageSize max 100).
`cloudbeds_get_reservations_with_rate_details`	Retrieve reservations with their financial breakdown and per-night rate details (subtotal, additional items, taxes and fees, grand total, amount paid, and a date-to-rate map per room). Use this when a guest asks how their total was calculated or what the nightly rate of their existing booking is. Pass reservationID (comma-separated for several) to target specific bookings — prefer that over unfiltered listing. For status/name/date searches use cloudbeds_get_reservations instead. Results are paginated (pageSize max 100).
`cloudbeds_get_room_blocks`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. List the property's room blocks (blocked dates, out-of-service blocks, courtesy holds) with their rooms and date ranges. Dates in ISO YYYY-MM-DD; both default to today and the date range must be 35 days or less. Filter by roomBlockID, roomTypeID, or roomID. For group inventory holds use the allotment-blocks tool instead.
`cloudbeds_get_rooms`	List the property's physical rooms (room name, description, max guests, room type, blocked flag). Use this for questions about specific rooms or the room inventory — for what CAN BE BOOKED on given dates use the availability tool instead. Optionally filter by roomTypeID or roomTypeNameShort. If startDate is provided (ISO YYYY-MM-DD; endDate then required), ONLY rooms UNASSIGNED to any reservation in that period are returned.
`cloudbeds_get_sources`	List the property's booking sources (direct website, Booking.com, walk-in, etc.) with their source IDs. This is a static configuration catalog — use it to understand where bookings originate or to resolve a sourceID mentioned on a reservation. It contains no guest data.
`cloudbeds_get_taxes_fees`	Retrieve the property's configured taxes and fees catalog (VAT, city tax, resort fees, etc.) — name, amount, amount type, and whether each is inclusive or exclusive of the rate. Use this to answer 'what taxes apply?', 'is VAT included?', or 'do you charge a city tax?'. To calculate the actual fee/tax amounts for a specific booking quote use the booking fees-and-taxes tool instead. Optionally filter by what the tax/fee applies to (availableFor).
`cloudbeds_list_allotment_block_notes`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. List the notes attached to an allotment block. Optionally filter by note status (all, active, archived). Note contents are returned in the 'message' field.
`cloudbeds_patch_group`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Update an existing group profile identified by groupCode — name, type, status (open/closed), source, or address. At least one field besides groupCode must be provided. To create a new group use the put-group tool instead.
`cloudbeds_post_adjustment`	OPERATOR-GRADE: changes folio MONEY totals — never use in guest conversations unless explicitly instructed. Add an adjustment to a reservation folio. type selects what the adjustment applies to: rate, product, fee, or tax. For product/fee/tax adjustments, itemID identifies the specific product, fee, or tax to adjust (not used for rate). The response returns the adjustmentID, which cloudbeds_delete_adjustment can void later. NEVER auto-retry this call after a timeout or ambiguous failure — the adjustment may already be applied; verify the current folio state first.
`cloudbeds_post_charge`	OPERATOR-GRADE: MOVES MONEY through the payment gateway — never use in guest conversations unless explicitly instructed. Process a real charge on a stored payment method (paymentMethodId) against a reservation, house account, group profile, or accounts-receivable ledger. Unlike cloudbeds_post_payment (which only RECORDS a payment), this actually charges the payment method via the gateway. amount is a decimal string; currency is a 3-letter ISO code. The response paymentStatus may be 'pending' when the card requires a 3-D Secure browser challenge — such charges cannot be completed through this tool. NEVER auto-retry this call after a timeout or ambiguous failure — the charge may already have been processed; verify the current payment state first.
`cloudbeds_post_custom_item`	OPERATOR-GRADE: posts charges to a folio — never use in guest conversations unless explicitly instructed. Post one or more CUSTOM (ad-hoc, non-catalog) items with optional payments to a reservation, house account, or group folio as a single transaction. Provide exactly one of reservationID, houseAccountID, or groupCode. Always set referenceID (your own unique transaction reference) — Cloudbeds uses it to prevent duplicate postings; a repeat call with the same referenceID is a no-op that returns a notice. For items already in the catalog use cloudbeds_post_item instead. CAUTION: itemPaid=true auto-registers a CASH payment for the full value (ignored when the payments array is provided). NEVER auto-retry blindly after a timeout — re-send only with the SAME referenceID so the dedup guard applies, or verify the folio state first.
`cloudbeds_post_group_note`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Add a free-text note to a group profile — e.g. special arrangements, billing instructions, or event details. groupCode identifies the group (from the groups tool).
`cloudbeds_post_guest`	Add a person to an existing reservation as an additional guest. Use this when the verified booker asks to add a travel companion to their booking. Requires the reservationID, the person's first and last name, email, and 2-letter ISO country code. To assign the added guest to a specific room afterwards, use cloudbeds_post_guests_to_room. To edit an existing guest use cloudbeds_put_guest.
`cloudbeds_post_guest_note`	Add a note to a guest's profile — e.g. a preference or request the guest shared ('prefers a high floor', 'arriving after midnight'). Never record payment card numbers or identity document numbers in a note. To change an existing note use cloudbeds_put_guest_note.
`cloudbeds_post_guests_to_room`	OPERATOR-GRADE: assign one or more guests to a room on a reservation (adding them as additional guests if needed) — never use in guest conversations unless explicitly instructed. guestIDs is comma-separated for multiple guests. Set removeAll=true to clear the room's existing guests first (the main guest is never removed). mainGuestId, when provided, promotes that guest (who must be in guestIDs) to main guest of the room.
`cloudbeds_post_house_account`	OPERATOR-GRADE: creates a billing folio — never use in guest conversations unless explicitly instructed. Create a new house account with the given name. Set isPrivate=true to make the account visible only to the creating user. Returns the new houseAccountID.
`cloudbeds_post_housekeeping_assignment`	OPERATOR-GRADE: changes live room assignments — never use in guest conversations unless explicitly instructed. Assign one or more rooms to an existing housekeeper. roomIDs is a comma-separated list of room IDs (e.g. 37,345,89 — from the housekeeping-status tool); housekeeperID comes from the housekeepers tool. Set housekeeperID to 0 to mark the rooms as UNASSIGNED. Verify the result with the housekeeping-status tool.
`cloudbeds_post_housekeeping_status`	OPERATOR-GRADE: changes a room's live housekeeping state — never use in guest conversations unless explicitly instructed. Update the housekeeping status of ONE room: set roomCondition to clean, dirty, or inspected ('inspected' only works when the property has that feature enabled), and/or set the doNotDisturb, refusedService, or vacantPickup flags, and/or replace the room comments. Only provided fields change; if roomCondition is omitted and no flags are sent, the condition toggles from its current value. Get roomID from the housekeeping-status tool.
`cloudbeds_post_item`	OPERATOR-GRADE: posts charges to a folio — never use in guest conversations unless explicitly instructed. Add an existing catalog item (by itemID from cloudbeds_get_items) to a reservation, house account, or group folio. Provide exactly one of reservationID, houseAccountID, or groupCode. CAUTION: itemPaid=true automatically registers a CASH payment for the full value including taxes and fees — leave it false and record payments explicitly (via the payments array or cloudbeds_post_payment) unless a cash payment is exactly what happened. saleDate is an ISO date-time and defaults to now. NEVER auto-retry this call after a timeout or ambiguous failure — the item may already be posted; verify the folio state first.
`cloudbeds_post_payment`	OPERATOR-GRADE: records a MONEY transaction — never use in guest conversations unless explicitly instructed. Record a payment against a reservation, house account, or group folio. Provide exactly one of reservationID, houseAccountID, or groupCode (if several are sent, precedence is reservationID, then houseAccountID, then groupCode). type must be one of the property's enabled payment methods — look them up with cloudbeds_get_payment_methods first; when type is 'credit', cardType is also required. Maison lifecycle: payments are recorded against a reservation, and after the reservation is fully paid its status is set to confirmed via cloudbeds_update_reservation. NEVER auto-retry this call after a timeout or ambiguous failure — the payment may already be recorded; verify the current payment state first.
`cloudbeds_post_reservation_document`	Attach a text document to a reservation (e.g. a written confirmation, itinerary, or correspondence transcript). The file content is sent as text. Use cloudbeds_post_reservation_note for short remarks — documents are for substantial content that staff need attached to the booking record. Returns the uploaded fileID.
`cloudbeds_post_reservation_note`	Add a note to a reservation (e.g. a guest request such as 'late arrival around 23:00' or 'anniversary stay'). Notes are visible to hotel staff, not to the guest. Use this to record guest preferences or requests against their booking. Returns the new reservationNoteID.
`cloudbeds_post_room_assign`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Assign, reassign, or unassign a physical room on a reservation. To assign: provide newRoomID and roomTypeID. To reassign: also provide oldRoomID. To unassign: provide reservationRoomID and an empty newRoomID. Set adjustPrice=true only when an upcharge or discount from the room change has been explicitly approved; otherwise the rate keeps its original value.
`cloudbeds_post_room_check_in`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Check in a room that is already assigned on a reservation. Provide subReservationID to target a specific room of a multi-room reservation (roomID is ignored when subReservationID is sent), or roomID alone. Verify the room's status first with cloudbeds_get_reservation_room_details.
`cloudbeds_post_room_check_out`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Check out a room on a reservation. When all rooms are checked out, the whole reservation status becomes checked_out. Provide subReservationID to target a specific room of a multi-room reservation (roomID is ignored when subReservationID is sent), or roomID alone. Check the outstanding balance first with cloudbeds_get_reservation_details.
`cloudbeds_put_group`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Create a NEW group profile (group, company, travel agent, or wholesaler) on the property — despite the 'put' name this ADDS a group. To modify an existing group use the patch-group tool instead. Returns the new group's groupCode.
`cloudbeds_put_guest`	OPERATOR-GRADE: update an existing guest's profile (name, contact details, address) — never use in guest conversations unless explicitly instructed. Requires guestID plus at least one field to change; omitted fields are left unchanged. Country is a 2-letter ISO code.
`cloudbeds_put_guest_note`	Update the text of an existing guest note. Requires the guestID, the noteID (from cloudbeds_get_guest_notes) and the replacement note text. To remove a note entirely use cloudbeds_delete_guest_note.
`cloudbeds_put_house_account_status`	OPERATOR-GRADE: changes a billing folio's status — never use in guest conversations unless explicitly instructed. Set a house account (by houseAccountID) to open or closed. Closed accounts no longer accept postings.
`cloudbeds_put_reservation_note`	Update the text of an existing reservation note, identified by reservationNoteID (from cloudbeds_get_reservation_notes). The new text replaces the old note content entirely.
`cloudbeds_update_allotment_block_note`	OPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Update or archive a note on an allotment block. noteID comes from the list-notes tool. Provide text to change the contents, and/or status 'archived' to archive it ('active' to restore).
`cloudbeds_void_item`	OPERATOR-GRADE: voids folio charges — never use in guest conversations unless explicitly instructed. Void a posted item transaction (by soldProductID, as returned by cloudbeds_post_item or cloudbeds_post_custom_item) on a reservation, house account, or group folio. CAUTION: any payments registered together with the item are deleted too. Provide exactly one of reservationID, houseAccountID, or groupCode. NEVER auto-retry this call after a timeout or ambiguous failure — the item may already be voided; verify the folio state first.
`cloudbeds_void_payment`	OPERATOR-GRADE: voids a MONEY transaction — never use in guest conversations unless explicitly instructed. Void an existing payment (by paymentID) on a reservation or house account. Provide reservationID, or houseAccountID when there is no reservationID. NEVER auto-retry this call after a timeout or ambiguous failure — the payment may already be voided; verify the current payment state first.