Skip to content
/
Migration guide
Last updated

RtB 2.0 migration guide

This guide walks you through upgrading your RtB integration to version 2.0.0. The key change: for RTB requests, you now block provider-side availability when the request is created, not when it is booked. Release it if the request is rejected, expires, or fails. Everything else in the guide adds the API fields to support that.

Before you start, read the RtB 2.0 overview to understand how the RTB flow differs from the INQUIRY flow, especially around inventory holds and payment.

Steps

  1. Confirm the property is eligible. RtB 2.0 has geographical, payment-model, and provider requirements. Check them in Eligibility before you begin.

  2. Send the new version header. Switch your requests to version 2.x by sending:

    X-Booking-Api-Version: 2.0.0

    Omitting the header keeps you on the default 1.0.1. See Versioning for the full version history.

  3. Handle the requestType field. Each Booking Request now carries requestType (INQUIRY or RTB). Branch your logic on it: RTB requests hold inventory while pending, INQUIRY requests do not. See New field: requestType.

  4. Implement status-based availability holds. For RTB requests, block provider-side availability at CREATED and release it on REJECTED, EXPIRED_PENDING_APPROVAL, and FAILED_TO_PROCESS, propagating each change across your channels. Do not re-block when the reservation later arrives via the Reservations API. See RtB 2.0 availability management.

  5. Handle the FAILED_TO_PROCESS status. Extend your internal model to accept this status and release any hold when it occurs. See New request status: FAILED_TO_PROCESS.

  6. Validate before going live. Run the self-assessment scenarios and share the RUIDs with your Booking.com contact.

  7. Go live by enabling the provider feature. Once your integration is built and validated, enable the rtb_api_v2_enabled provider feature in Provider Portal. Only then will your properties begin receiving RTB requests. Until it is enabled, all requests continue to use requestType = INQUIRY.

Enable only after migration is complete

Enable rtb_api_v2_enabled only once your integration handles the new fields and availability rules. Turning it on before you are ready means your properties start receiving RTB requests you cannot process correctly, which can break bookings.

Next step: support guest withdrawals (upgrade to 2.1.0)

Once you are live on 2.0.0, the recommended next step is to adopt the withdrawal feature by bumping to X-Booking-Api-Version: 2.1.0, an incremental release on top of 2.0.0. It adds the WITHDRAWN_PENDING_APPROVAL status. For RTB requests, you handle it by releasing the inventory hold, the same way you handle REJECTED. For INQUIRY requests there is no inventory hold to release, so you mark the request as withdrawn. See Handling guest withdrawals. For the full list of versions and what each adds, see Versioning.

Overview

Eligibility