Sell rates quick guide
Learn how to get the best value to your travellers by having Sell rates enabled.
Retrieving Sell rates
You can retrieve Sell rates when using our accommodation endpoints.
Depending on the sort of integration you are implementing, you should use different endpoints:
Content only
Share our content with your audience and redirect them to our platform to book. For this integration use accommodation/search endpoint.
Entire booking journey
Allow your audience to search, look and book their stays on your website. For this integration use the full set of accommodation endpoints.
Check the Acommodation Quick guide for general instructions on how to use Demand API endpoints for stays.
Refer to our examples for details on how to implement each of these requirements in your requests.
Content only
If you are only retrieving our content ("Content only" integration), then you must call our accommodation/search endpoint.
You will receive the best price as search output, which could be either from a third party or Booking.com inventory based on rates ranking.
To retrieve Sell rates, ensure that your request:
| ✓ Is for 1 room booking (with single or multiple occupancy). |
|---|
Examples:
→ Call the accommodation/search endpoint.
In this example, the request is for 1 room booking, with 3 adult occupancy for the specified dates.
Sell rates are currently only retrieved when searching for 1 room (with single or multiple occupancy).
Example:
{
"booker": {
"country": "nl",
"platform": "desktop"
},
"checkin": "2025-12-15",
"checkout": "2025-12-18",
"city": -2140479,
"extras": [
"products"
],
"guests": {
"number_of_adults": 3,
"number_of_rooms": 1
}
}
Refer to the accommodation search guide for more details about mandatory fields and search behaviour.
Look and book with whilelabel
When performing the Look and book part of the flow using whitelabel, you receive the sell rates on the branded landing platforms of Booking.com tagged as “Partner Offer” in our user interface.
Then you can market it using whitelabel.
Example:
Entire booking experience
If you are implementing an end-to-end booking experience (Search, look and book integration), then you must cover the full accommodation API flow.
In each of the steps you can identify whether a product comes from a Third party inventory and offers Sell rates or not, by checking the inventory object and the third_party_inventory tag.
You can find these components within the successful response of the calls.
Refer to the Accommodation quick guide for instructions on all the steps and endpoints.
Prerequisites
To enjoy the benefits of Sell rates, you must first meet these requirements:
Checklist | |
|---|---|
| ☑ | your partner agreement must authorise you to use online payments (pay_online_now). |
| ☑ | you can use virtual credit cards and/or credit card payment methods. |
Contact your account manager if you meet these requirements and would like to enable Sell rates.
Key parameters in requests
To retrieve Sell rates, ensure that your requests:
| ✓ | Are for 1 room only request (with single or multiple occupancy) |
| ✓ | Use pay_online_now timing (pay_online_later is not yet accepted). |
| ✓ | Set the payment: prepayment_required field to "true" since Sell rates are all prepaid. |
| ✓ | Include either a Credit card or Virtual credit card as payment method. Other payment methods are not compatible with Sell rates. |
Look at availability
→ Call the accommodation/availability endpoint with the desired accommodation ID and same details returned from the search request to provide real-time information about availability and rates.
Refer to the Accommodations quick guide for more details on how to use this endpoint.
Inventory type
The response returns a list of available products with the best price for your search criteria (one room, pay online now, etc.)
When retrieving Sell rates:
The
inventoryobject specifies that the product comes from a third party inventory (as this is set to true) and thetypeof rates identifies it as "Sell" rates.Also, the room overall
third_party_inventoryfield is set to true.The
paymentobject includes:prepayment_requiredfield set to true.- The
pay_online_nowtiming.
Example:
{
"request_id": "01j6en0kkx6ve7eyd8nmh6knaz",
"data": {
"id": 2489623,
"currency": "EUR",
"deep_link_url": "booking://hotel/2489623?affiliate_id=1234567&checkin=2024-12-15&checkout=2024-12-18",
"products": [
{
"id": "tpi-f621534d2037f346ff4b80c090072866",
"deal": null,
"inventory": {
"third_party": true,
"type": "sell"
},
"maximum_occupancy": {
"adults": 3,
"children": null,
"total": 3
},
"number_available_at_this_price": 1,
"policies": {
"cancellation": {
"free_cancellation_until": "2024-12-13T16:59:59+00:00",
"type": "free_cancellation"
},
"meal_plan": {
"meals": [],
"plan": "no_plan"
},
"payment": {
"prepayment_required": true,
"timings": [
"pay_online_now"
]
}
},
"price": {
"book": 58.03,
"total": 58.03
},
"room": 248962301,
"third_party_inventory": true
},
...
],
"recommendation": null,
"url": "https://www.booking.com/hotel/th/kallapangha-resort.html?aid=1234567&checkin=2024-12-15&checkout=2024-12-18&no_rooms=1&group_adults=1&selected_currency=EUR"
}
}
Preview the booking
For the booking, you need to use the order/preview endpoint first.
Refer to the Orders guide for instructions on how to construct your requests and examples.
In the response you can see the order details, including price breakdown and available payment methods.
When retrieving Sell rates:
The
inventoryobject specifies that the product comes from a third party inventory (as this is set to true) and thetypeof rates identifies it as "Sell" rates.Also, the room overall
third_party_inventoryfield is set to true.The
paymentobject includes:prepayment_requiredfield set to true.- The
pay_online_nowtiming.
Example of Orders/preview response
{
"request_id": "01j6en7frsgv9wweyt5z9fhdee",
"data": {
"accommodation": {
"id": -2140479,
"currency": {
"accommodation": "THB",
"booker": "EUR"
},
"general_policies": {
"payment": {
"pay_at_the_property": null,
"pay_online_later": null,
"pay_online_now": {
"method_required": true,
"dates": [
{
"at": "2024-08-29",
"price": {
"accommodation_currency": 2198.97,
"booker_currency": 58.03
}
}
],
"methods": {
"airplus": true,
"wallet": false,
"cards": [
1,
44,
5,
11,
7,
3,
2
]
}
}
}
},
"price": {
"base": {
"accommodation_currency": 1868.05,
"booker_currency": 49.30
},
"extra_charges": {
"non_conditional": [
{
"charge": 1,
"total_amount": {
"accommodation_currency": 167.50,
"booker_currency": 4.42
}
},
{
"charge": 23,
"total_amount": {
"accommodation_currency": 163.42,
"booker_currency": 4.31
}
}
]
},
"total": {
"accommodation_currency": 2198.97,
"booker_currency": 58.03
}
},
"products": [
{
"id": "tpi-f621534d2037f346ff4b80c090072866",
"policies": {
"cancellation": [
{
"from": "now",
"price": {
"accommodation_currency": 0.00,
"booker_currency": 0.00
}
},
{
"from": "2024-12-13T18:00:00",
"price": {
"accommodation_currency": 2198.97,
"booker_currency": 58.03
}
}
],
"meal_plan": {
"meals": [],
"plan": "no_plan"
}
},
"price": {
"base": {
"accommodation_currency": 1868.05,
"booker_currency": 49.30
},
"extra_charges": {
"non_conditional": [
{
"charge": 1,
"mode": "calculated_amount",
"percentage": null,
"total_amount": {
"accommodation_currency": 167.50,
"booker_currency": 4.42
},
"unit_amount": null
},
{
"charge": 23,
"mode": "calculated_amount",
"percentage": null,
"total_amount": {
"accommodation_currency": 163.42,
"booker_currency": 4.31
},
"unit_amount": null
}
]
},
"total": {
"accommodation_currency": 2198.97,
"booker_currency": 58.03
}
},
"third_party_inventory": true
}
]
},
"order_token": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7ImFjY29tbW9kYXRpb24iOnsiaWQiOjI0ODk2MjMsImNoZWNraW4iOiIyMDI0LTEyLTE1IiwiY2hlY2tvdXQiOiIyMDI0LTEyLTE4IiwiY3VycmVuY3kiOiJUSEIiLCJwcm9kdWN0cyI6W3siaWQiOiJ0cGktZjYyMTUzNGQyMDM3ZjM0NmZmNGI4MGMwOTAwNzI4NjYiLCJhbGxvY2F0aW9uIjp7ImNoaWxkcmVuIjpbXSwibnVtYmVyX29mX2FkdWx0cyI6MX0sInRvdGFsX3ByaWNlIjoyMTk4Ljk3fV19LCJib29rZXIiOnsiY291bnRyeSI6Im5sIiwicGxhdGZvcm0iOiJkZXNrdG9wIiwidHJhdmVsX3B1cnBvc2UiOiJsZWlzdXJlIn0sImJvb2tlcl9jdXJyZW5jeSI6IkVVUiJ9LCJhdWQiOiIvb3JkZXJzL2NyZWF0ZSIsImV4cCI6MTcyNDkyNDk5N30.64SF7j3sBneoTsLQkig7uJi-HnaY1SZVdsUHrSTRp_c"
}
}
Create the booking
The final step in the full booking experience is to use the order/create endpoint, to finish the booking by proceeding the payment.
Refer to the Orders guide for more details about mandatory fields, examples and recommendations for your requests.
The response retrieves the receipt URL, the order, pincode and reservation ID.
Example:
{
"request_id": "01j69mtd91x3pdcmqyj0spebt9",
"data": {
"payment": {
"receipt_url": "https://secure.booking.com/payment_receipt.html?product_type=BookingBudget&aid=2373042&auth_key=8riKJJ0XuxDhk4ds&lang=en",
"authorisation_form_url": null
},
"accommodation": {
"order": "5006302528200239",
"pincode": "884512"
}
}
}
Your order ids
A successful order/create response returns the following ids:
- Order ID: This is the booking number that you should use to cancel an order.
- Pincode: This is a shorter number that identifies your booking and is handy when contacting Customer Services. It is also included in the booking confirmation message.
Example of confirmation message for a third-party inventory booking (Partner offer), with order id and pin code:
In rare occasions the order might return a reservation id. This is a V2 legacy. You should only use this if you need to access orders created using Demand API V2 after you have migrated your integration to V3.
Cancellation restrictions
Please be aware that if you need to cancel a booking for a third-party inventory accommodation, you must follow the same instructions and best practices as outlined for other accommodation types in the Handling cancellations guide.
However, there are some restrictions:
| Cancellation policy | |
|---|---|
| ✓ Flexible-free | If the third-party rates product is subject to this policy you can cancel the order via the /orders/cancel endpoint. |
| ✗ Non-refundable | If the product is under this policy you are not allowed to cancel your order using the /orders/cancel endpoint. If you attempt to do so, you will receive a 500 error code. |
| ✗ Parcially refundable (special conditions) | This sort of policy is not supported. |
Example of non-refundable policy
When you call the accommodation/availability endpoint, the response will include the cancellation policy associated to the third-party inventory block.
- To identify the policy type, check under
"policies" -> "cancellation" -> "type".
In this example, the policy is non-refundable, so the free_cancellation_untilfield appears as null.
{
"id": "tpi-704220a9543ce3c4452180d1c227c20d",
"deal": null,
"inventory": {
"third_party": true,
"type": "sell"
},
"maximum_occupancy": { ... },
"number_available_at_this_price": 1,
"policies": {
"cancellation": {
"free_cancellation_until": null,
"type": "non_refundable"
},
"meal_plan": {
"meals": [],
"plan": "no_plan"
},
"payment": {
"prepayment_required": true,
"timings": [
"pay_online_now"
]
}
},
"price": {
"book": 9179.11,
"total": 9179.11
},
"room": 277323201,
"third_party_inventory": true
}
Important consideration
If the booked property is subject to the non-refundable policy, you will not be able to cancel the order using the orders/cancel endpoint.
- Refer to the Accommodations quick guide for instructions on how to use the full set of accommodation endpoints.
- Check the orders section for more information about how to create orders and look at their details.
- Learn about supported cancellation policies and how to cancel an order.