This self-assessment tutorial is to help you cover various RtB scenarios and make sure your implementation works as expected.
In this self-assessment tutorial, you will:
- Create a new RtB enabled property or enable an existing RtB eligible property.
- Create an RtB request using the frontend app for an RtB eligible and enabled property.
- Retrieve RtB requests in bulk using the RtB API.
- Retrieve a specific RtB request using the RtB API.
- Update the status of an RtB request using the RtB API.
You should read this if any of the following applies to you:
- If you want to estimate the time needed to implement the RtB API
- If you want to try out most of the essential endpoints of RtB API on a test environment
- If you are preparing to implement the RtB API, or have implemented and want to validate your implementation
A machine account with permissions to call Reservations API. You can create machine accounts using the connectivity portal.
- Only works for test properties. Real properties must use the regular flow via the property page.
- The single room restriction is not applied at the form. But it's still enforced later. So you can only make requests for a single room.
- Login is required, anonymous requests are not allowed.
Create a new test property with the booking model: RTB.
Alternatively, you can use an existing eligible test property, and leverage Content API to change it's booking model to RtB. See the onboarding article to learn more.
Do not forget to add availability for the dates that you want to request to book for.
Follow this link to create a new request (remember to provide your test property ID):
https://secure.booking.com/book.html?test=1;hotel_id={property_id}You must select a date that's at least 2 days in the future.
If the page redirects you to the search results page, then that indicates a lack of availability on the selected check-in date & number of nights. Make sure there is availability by going to the property's Extranet page.
You’ll see this page where you can enter the message that’ll be sent to the property.
You should be logged into your Booking account for this step.
Once you type a message and click on Request to Book, your request will be sent to the property.
After sending the making the booking request, in the url of the above page, make a note of the request id at the end &request={request_id}. We’ll use this id to fetch the request details and update its status later on.
At this step, you – as the guest – should receive an email informing you that your request has been sent.
This email looks like this:
You – as the property – should also receive an email informing you that you received a booking request.
This email looks like this:
Similarly, create 4 such RtB requests and note all the request IDs. Once we have the IDs, we will use them for the following scenarios:
- Request ID 1: This one will expire at the partner side.
- Request ID 2: This one will be rejected by the partner.
- Request ID 3: This one will be approved by the partner, but we’ll let it expire on guest side.
- Request ID 4: This one will be approved by the partner and booked by the guest.
Send a request using the following method and URL to get all the RtB requests.
Request:
GET https://supply-xml.booking.com/rtb/requestsSample request:
curl --location 'https://supply-xml.booking.com/rtb/requests?status=CREATED&updatedSince=2024-05-05T13:16:18Z' \
--header 'Authorization: Basic {your_base64_encoded_credentials}'
--header 'X-Booking-Api-Version: {version_number}'Sample response:
{
"data": [{
"id": 737767,
"propertyId": 10125435,
"requestStatus": "EXPIRED_PENDING_APPROVAL",
"checkin": "2023-06-23",
"checkout": "2023-06-24",
"totalPrice": {
"amount": 365.0,
"currency": "EUR"
},
"units": [{
"id": 738539,
"rateId": 35579440,
"name": "One-Bedroom Apartment",
"price": {
"amount": 365.0,
"currency": "EUR"
}
}],
"occupancy": {
"adults": 1,
"children": 0,
"total": 1
},
"guestInfo": {
"guestMessage": "ftbvznw ifs adyk xnwffhch"
},
"statusUpdateTime": "2023-05-26T13:28:54Z",
"createdAt": "2023-05-25T13:27:47Z",
"updatedAt": "2023-05-26T13:28:54Z"
}, {
"id": 686410,
"propertyId": 10122635,
"requestStatus": "EXPIRED_PENDING_APPROVAL",
"checkin": "2023-06-24",
"checkout": "2023-06-25",
"totalPrice": {
"amount": 392.49999999999994,
"currency": "EUR"
},
"units": [{
"id": 683222,
"rateId": 35939440,
"name": "One-Bedroom Apartment",
"price": {
"amount": 392.49999999999994,
"currency": "EUR"
}
}],
"occupancy": {
"adults": 2,
"children": 0,
"total": 2
},
"guestInfo": {
"guestMessage": "ktsxq oobh. vki yea mjo wkyh: oesw lswv bgvrc wal pmujo dhpc"
},
"statusUpdateTime": "2023-05-26T13:28:54Z",
"createdAt": "2023-05-25T13:27:47Z",
"updatedAt": "2023-05-26T13:28:54Z"
}
],
"warnings": [],
"errors": [],
"meta": {
"ruid": "0000000000000000000000000000000000000000000000000000000000000000000000000000",
"hasNextPage": true,
"nextPageUrl": "https://supply-xml.booking.com/rtb/requests?propertyId=10125435&status=EXPIRED_PENDING_APPROVAL&page=2&pageSize=2"
}
}Request:
GET https://supply-xml.booking.com/rtb/properties/{property_id}/requests/{request_id}Sample request:
curl --location 'https://supply-xml.booking.com/rtb/properties/{property_id}/requests/{id}' \
--header 'Authorization: Basic {your_base64_encoded_credentials}'
--header 'X-Booking-Api-Version: {version_number}'Sample response:
{
"data": [{
"id": 8744916,
"propertyId": 9575899,
"reservationId": 4257108177,
"requestStatus": "BOOKED",
"checkin": "2024-01-31",
"checkout": "2024-02-01",
"totalPrice": {
"amount": 150.0,
"currency": "EUR"
},
"units": [
{
"id": 957589902,
"rateId": 33417965,
"name": "Double Room",
"price": {
"amount": 150.0,
"currency": "EUR"
}
}
],
"occupancy": {
"adults": 2,
"children": 0,
"total": 2
},
"guestInfo": {
"guestMessage": "Hi, we would like to stay at your property for a night to explore the area.",
"emailVerified": false,
"phoneVerified": false,
"registeredSince": 2017,
"domestic": false,
"hasNoShow": false,
"hasPastMisconduct": false,
"hasStayWithPartnerBefore": true,
"completedStays": null
},
"statusUpdateTime": "2024-01-29T11:30:02Z",
"createdAt": "2024-01-29T11:28:41Z",
"updatedAt": "2024-01-29T11:30:02Z",
"expiresAt": null
}],
"warnings": [],
"errors": [],
"meta": {
"ruid": "7b4e2580-33a7-46cb-a007-10d1e940ee0f"
}
}Visit retrieving booking requests page to learn more about fetching RtB requests in bulk or by ID.
This section is only applicable if you have implemented the Messaging API. For more information, see the Messaging API documentation.
Request:
GET https://supply-xml.booking.com/messaging/properties/{property_id}/conversations/type/request_to_book?conversation_reference={request_id}Sample request:
curl --location 'https://supply-xml.booking.com/messaging/properties/2342343/conversations/type/request_to_book?conversation_reference=8744916' \
--header 'Authorization: Basic {your_base64_encoded_credentials}'Sample response:
{
"data": {
"ok": true,
"conversation": {
"conversation_id": "12345678-d1f2-5571-91a6-901730ea9678",
"conversation_type": "request_to_book",
"conversation_reference": "8744916",
"access": "read_write",
"messages": [
{
"message_id": "12345678-ede0-11ef-8002-0001013a637a",
"attachment_ids": [],
"timestamp": "2025-02-18T11:43:59Z",
"tags": {
"read": {
"set": false
}
},
"sender_id": "12345678-872c-5307-82b0-ddd34812253a",
"content": "RTB messaging test"
}
],
"participants": [
{
"participant_id": "12345678-4c2f-54ce-9a1d-9ea123c21993",
"metadata": {
"id": "2342343",
"type": "property"
}
}, {
"participant_id": "12345678-872c-5307-82b0-ddd34812253a",
"metadata": {
"type": "guest"
}
}
],
"tags": {
"no_reply_needed": {
"set": false
}
}
}
},
"errors": [],
"warnings": [],
"meta": {
"ruid": "0000000000000000000000000000000000000000000000000000000000000000000000000000"
}
}Request:
POST https://supply-xml.booking.com/messaging/properties/{property_id}/conversations/{conversation_id}Sample request:
curl --location 'https://supply-xml.booking.com/messaging/properties/2342343/conversations/c9ee7800-d1b1-11ef-91d9-230dcfbcbe1a' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {your_base64_encoded_credentials}' \
--data '{"message": {"content": "This is a test message sent from the partner"} }'Sample response:
{
"data": {
"ok": true,
"guest_has_account": true,
"message_id": "12345678-ede0-11ef-8002-0001013a637a"
},
"warnings": [],
"errors": [],
"meta": {
"ruid":"0000000000000000000000000000000000000000000000000000000000000000000000000000"
}
}Request:
curl --location 'https://supply-xml.booking.com/rtb/properties/2342343/requests/fc521d813a3423b2fc521d813a3423b2' \
--header 'Authorization: Basic {your_base64_encoded_credentials}' \
--header 'X-Booking-Api-Version: {version_number}' \
--data '{"status": "REJECTED", "rejectionReason": "POLICY_DONT_FIT_NEEDS",}'Sample response:
{
"warnings": [],
"errors": [],
"meta": {
"ruid": "0000000000000000000000000000000000000000000000000000000000000000000000000000"
}
}Request ID 1: Leave it for one day. The request should expire due to property inaction.
Request ID 2: Reject the booking request as shown above.
Request IDs 3 & 4: Use the above method with status as APPROVED and no rejection reason.
Request ID 3: Leave the request with ID 3 for one day. It should expire due to guest inaction.
Request ID 4: To book the request with ID 4, go to the email you received after the partner accepted your request, it should look as follows:
Click on Finish my booking. You should see a page like the following where you can fill your information and complete the reservation.
When the booking request transitions to the BOOKED state, this means the guest completed the reservation.
An RtB reservation is the same and behaves the same as a regular reservation.
The response JSON will contain reservation_id property if the status is BOOKED. You can use this reservation_id to fetch the reservation details using the reservation API.
Now, fetch all the booking requests using the LIST endpoint and verify their statuses.
You must display the non-discrimination policy and the information messaging when onboarding a partner and accepting/rejecting booking requests respsectively.
For more details, see the onboarding article.
The self-assessment is complete if all the steps were successful and the non-discrimination policy and the RtB information messaging is displayed on the relevant places.