FAQ

Terminology

OTA: Online travel agency (ex: booking.com, or competitor)
cid: Channel ID - a two to four character code used by Cloudbeds uniquely identify an OTA.
guid: Globally unique identifier, a unique 36 character code which identifies a request. Useful for seeing if a request is a retry and for debugging.

Requests

Cloudbeds will send requests to the OTA with content-type application/json, with the payload being in the body of the request. Gzip compression and keep-alives will be used if supported. HTTPS (SSL encryption) is required for the OTA's endpoint. If an endpoint with a port other than 443 is to be used Cloudbeds will need to allow-list this port first.

HTTP response codes from Cloudbeds should always be 200. They have the content-type application/json.

Required API calls

As a minimum these API calls need to be implemented on the OTA side:

HealthCheck
SetupProperty
GetRoomTypes
GetRatePlans
ARIUpdate
GetBookingList
GetBookingId

If the OTA has multiple properties under one user account these API calls are required in addition:

GetSubProperties

Credit/debit card data

If your channel transmits guest credit/debit card data to Cloudbeds, the following applies:

A PCI Attestation of Compliance (AoC) document must be provided to Cloudbeds and approved before card data can be enabled for your channel.
Cloudbeds must configure your channel for card handling on our side, so please let us know — during onboarding, or before you start sending card data — that your channel handles card data.
Card data is not accepted at the standard BookingCreate endpoint. Bookings containing card data must be sent to a dedicated, PCI-compliant endpoint that Cloudbeds provides for your channel. Requests to it are authenticated with the tx-proxy-key header issued by Cloudbeds, or from source IP addresses you supply for allow-listing. See the BookingCreate documentation for details.
For GetBookingId, card retrieval is handled over a secure path configured on the Cloudbeds side; your channel returns the Payments object as documented in the booking format.
Bookings containing card data are rejected when sent via BookingCreate, and silently dropped (not imported, since no error can be returned) when returned via GetBookingId, unless your channel has been enabled for card handling.

Channel Manager, CRS and Broker handling

If the OTA is a channel manager, a CRS (central reservation system) or otherwise a broker that relays bookings from other OTAs/sources then Cloudbeds need to be notified about this to mark the OTA as a "broker". Additionally, the booking format requires providing additional fields to ensure that properties can correctly map sources for reports, tax/fee handling and display purposes.

The following booking format fields are required for brokered bookings to work correctly:

OrderSource
OrderSourceId
ExternalReferences

Please check booking format on how to use these fields. We also recommend implementing the SourceTree field if multiple sources can be involved in a booking.

Following is an example of a booking that originally came through Expedia:

{
  "OrderSource": "Expedia",
  "OrderSourceId" : "exp",
  "ExternalReferences" : [
     {
        "Type" : "OTA",
        "Reference" : "2280949650"
     }
  ]
}