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.
-
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 theroomID
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. (*)
To retrieve availability rates and restrictions from myfrontdesk, you can use one of the following endpoints: (*)
-
You can retrieve ARI information with getRatePlans, including the
startDate
andendDate
.
Using thedetailedRates
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 andtotalRate
includes the supplements for any extra guests.
If no occupancy is passed in the request,roomRate
andtotalRate
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
, thederivedType
,derivedValue
andbaseRate
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 theroomTypeID
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.
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…) andbalance
the amount pending payment. ThebalanceDetailed
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.
-
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.
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.
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
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.
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.
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’ and you may need to seek further clarification from the property owner about their real vs. virtual inventory. Currently, our API does not support differentiating those.
Comments
0 comments
Please sign in to leave a comment.