Revenue Management systems pull availability, rate and reservation information from Cloudbeds with the aim of generating and posting back price recommendations for the properties.

(*) Mandatory requirements for Revenue Management System (RMS) functionality certification.

Initial pull

• Initially, you will need to pull a list of rooms to create or map them to the rooms in your system. For that purpose, you'll use getRoomTypes or getRooms. Rooms are nested under room types. (*)
  • The roomTypeID identifies the room type (e.g. double room) and the roomID points out the specific physical room.
  • The roomTypeUnits parameter in getRoomTypes shows the total number of units of each accommodation type (regardless of the occupancy status) and can be used to build the total property inventory on your side.
• Use getRatePlans to retrieve the rate configuration. You can only update rates with isDerived set to false. (*)

Retrieve ARI from Cloudbeds PMS

To retrieve availability rates and restrictions from Cloudbeds, you can use one of the following endpoints: (*)

• You can retrieve ARI information with getRatePlans, including the startDate and endDate.
  Using the detailedRates parameter returns daily rates, availability, and restrictions (CTA, CTD, minLOS, maxLOs…)
  • roomsAvailable informs of the rooms available. Cloudbeds availability is at room level, so all the rates linked to a particular room type (roomTypeID) will return the same availability in the roomsAvailable parameter.
  • All Cloudbeds properties have a base rate (BAR rate) per room type and, optionally, additional standalone or derived rate plans linked to all or some room types.
    The additional rate plans can be identified with some parameters that do not show for the base rates (ratePlanID, ratePlanNamePublic and ratePlanNamePrivate).
  • Based on the number of adults and children included in the request, roomRate shows the rate for the base occupancy and totalRate includes the supplements for any extra guests.
    If no occupancy is passed in the request, roomRate and totalRate will both show the default occupancy rate.
  • The rateID parameter is unique per room type/rate combination across all Cloudbeds properties. You need to save it and include it on any rate update requests.
  • When derived : true, the derivedType, derivedValue and baseRate parameters are displayed so you can work out the calculation.
    All rate plans are derived from the base rate for the corresponding room.
• If you only require information on base rates, you may use getRate with detailedRates : true instead of getRatePlans. Only the base rate of the roomTypeID included in the request will be returned.

**The rates returned in getRatePlans or getRate will be tax-inclusive or exclusive according to the property setup that can be retrieved via the getTaxesAndFees endpoint.

Pull reservations from Cloudbeds

We strongly recommend subscribing to our Webhooks to be notified about new reservations and reservation changes updates.

• Reservation created: Notifies when a new reservation is created in Cloudbeds or by a third party app.
• Please see the Webhook Guide for full details and all available Webhooks related to possible reservation changes:
  • status_changed, dates_changed, accommodation_status_changed, accommodation_type_changed, accommodation_changed, deleted.

Use getReservations with parameters status or CheckInFrom/CheckInTo and CheckOutFrom/CheckOutTo to get a list of reservations for your specific purpose.

• You can retrieve more specific reservation information by calling individual reservations with getReservation, getReservationsWithRateDetails or getReservationInvoiceInformation.
  • getReservation: You can retrieve information on the booked rooms in the assigned / unassigned arrays to deduct the booked rooms from the inventory.
    As for the reservation revenue, total shows all the reservation charges (room revenue, items…) and balance the amount pending payment. The balanceDetailed array includes information about balance, items, taxes and payments.
  • getReservationsWithRateDetails includes a detailedRates array that returns daily rates per room booked.
  • If you require detailed reservation invoicing information, including items, add-ons, payments, and adjustments, you can use the getReservationInvoiceInformation endpoint.
  • To analyze reservation revenue for past bookings, you can also use the getTransactions endpoint. This endpoint only returns posted transactions, so any pending transactions for current/future bookings will not be returned.

Update rates and restrictions in Cloudbeds

We strongly recommend subscribing to api_queue_task/rate_status_changed webhook to be notified of the job status changes.

• Please see the Webhook Guide for full details and all available Webhooks.

Use patchRate to post rate and restriction updates to Cloudbeds. As this endpoint is asynchronous, you should save the jobReferenceID returned in the response for troubleshooting. Only non-derived rates can be updated. (*)

• The rateID parameter can be pulled from the getRatePlans or getRate response.
• You can make multiple rate updates in a single API call (up to 30 intervals).
• Only non-derived rates can be updated, requests to update a derived rate will return an error.
• This endpoint performs updates asynchronously, rate updates are added to a queue and the endpoint returns a job reference ID. This job reference ID can be used to track job status notifications or to look up details of the update once it is completed.
• The parameters can be sent as raw JSON or form data in the request.

curl --location 'https://hotels.cloudbeds.com/api/v1.1/patchRate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **' \
--data '{
"rates": [
    {
        "rateID" : "456664",
        "interval": [
            {
                "startDate": "2023-11-14",
                "endDate": "2023-11-14",
                "rate": 125,
                "minLos": 4,
                "maxLos": 10,
                "closedToArrival": true,
                "closedToDeparture": true,
                "cutOff": 2,
                "lastMinuteBooking": 5
                
            }
        ]
    }
]
}

• Validate that the jobReferenceID has been successfully processed with getRateJobs, we strongly recommend instead subscribing to the api_queue_task/rate_status_changed webhook to be notified of the job status changes. (*)
• As a general rule, properties should be advised to have intervals loaded in Cloudbeds for the next 18 months (or any higher period).
  However, if you send a rate update for a period where no interval is available, the interval will be automatically created in Cloudbeds. Unless you include restrictions in your request, the interval will be created with no restrictions or occupancy supplements. The property should be advised to block their rooms or set a stop sell for the periods where they are not bookable.
  Additional occupancy supplements (OBP) can only be managed in the user interface.
• We encourage you to send simultaneous updates within our rate limits as they will be processed asynchronously.
• The rate parameter is optional for patchRate requests, so it is possible to send a request to only update a restriction such as minimum stay or close to arrival.

Room Blocks

We strongly recommend subscribing to our Webhooks: roomblock/created, roomblock/removed and roomblock/details_changed

• Please see the Webhook Guide for full details and all available Webhooks

Use getRoomBlocks to retrieve any out-of-service or blocked rooms, we strongly recommend subscribing to our webhooks as an alternative option.

For additional information on room blocks, review Manage blocks on the calendar. The API supports 'blocked dates' and 'out-of-service room blocks.

Allotment Blocks

Use getAllotmentBlocks to retrieve any group booking allotments and the pickup status against those blocks. You can also subscribe to the allotmentBlock/created, allotmentBlock/updated and allotmentBlock/deleted webhook.

Cloudbeds Groups is an optional module which not all Cloudbeds customers will be leveraging, but -when in use- it will allow you to reconcile differences in availability and bookings for each roomType daily. Reservations associated with an allotmentBlock will include the allotmentBlockCode in the response to /getReservation.
Additional documentation: Groups

FAQ

Can derived rates be updated?

Derived rates are not directly modifiable via the API, but the BaseRate upon which they are based may be altered. For example, a ‘10% discount’ derived rate would apply to whatever you specify as the Base rate for a specific room type.

How are default and additional occupancies managed in Cloudbeds?

The getRoomTypes endpoint includes the default and maximum occupancy information for each room type. Updates sent by patchRate update the default occupancy and any supplements configured in Cloudbeds for the additional occupancies will be applied based on the new default occupancy rate.
It is not possible to update the additional occupancy supplements via our API.

What is the split inventory functionality?

Some Cloudbeds customers may be using the split inventory functionality that allows them to sell the same physical room under different configurations. For example, several rooms can be sold separately or as the entire floor.
The getRooms or getRoomTypes endpoints return the full list of ‘physical’ and ‘virtual rooms’. getRooms includes the isVirtual parameter to identify the split inventory rooms.

Currently, our API does not support differentiating those.