Self-assessment tutorial: RtB API

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:

1. Create a new RtB enabled property or enable an existing RtB eligible property.
2. Create an RtB request using the frontend app for an RtB eligible and enabled property.
3. Retrieve RtB requests in bulk using the RtB API.
4. Retrieve a specific RtB request using the RtB API.
5. Update the status of an RtB request using the RtB API.

Who is this for?

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

Before you start

Please observe the following constraints when using this testing approach

• 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.

Step 1: Create a new RtB property or enable an existing eligible RtB property

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.

Step 2: Create a booking request from frontend app

2.1. Create a new booking request

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}

2.2. Select a room and click on I'll reserve

2.3. Write a message and request to book

You’ll see this page where you can enter the message that’ll be sent to the property.

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.

2.4. Check your email

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.

Step 3: Retrieve booking requests

Send a request using the following method and URL to get all the RtB requests.

Request:

GET https://supply-xml.booking.com/rtb/requests

Sample 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"
  }
}

Step 4: Retrieve a specific booking request by ID

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.

Step 5: Update the status of a booking request

Request:

POST https://supply-xml.booking.com/rtb/properties/{property_id}/requests/{request_id}

Sample 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"
    }
}

Let's run through various RtB scenarios

1. Expired at the property side

Request ID 1: Leave it for one day. The request should expire due to property inaction.

2. Booking request rejected

Request ID 2: Reject the booking request as shown above.

3. Booking request approved

Request IDs 3 & 4: Use the above method with status as APPROVED and no rejection reason.

4. Expired at the guest side

Request ID 3: Leave the request with ID 3 for one day. It should expire due to guest inaction.

5. Booked

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.

Now, fetch all the booking requests using the LIST endpoint and verify their statuses.

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.