Search, look and book TPI rates
This guide walks you through the end-to-end flow for retrieving and booking third-party inventory (TPI) rates using the Demand API.
Search, look and book flow overview
This guide covers the full end-to-end booking flow (Search, look and book integration), explaining how to:
- Filter for TPI-eligible products in your accommodations/search call.
- Understand the response fields that indicate TPI rates availability.
- Avoid common pitfalls such as multi-room requests or unsupported payment methods.
- Display returned TPI rates in your application.
- Offer the supported payment method to initiate the booking.
You can use TPI rates with either Sell or Net business models, depending on your integration setup.
Requirements
Before integrating TPI rates, ensure your setup meets the following requirements:
Checklist | ||
|---|---|---|
| ☑ | Version |
|
| ☑ | Authentication |
|
| ☑ | TPI eligibility |
|
Step-by-step flow
To support the full booking experience, follow these steps:
Search & look flow:
- Search for eligible properties using the accommodation/search endpoint.
- Look up availablity, pricing and policies at accommodations/availability endpoint.
- Display TPI rates to your travellers.
- Show the retrieved TPI rates to your travellers in your booking flow.
- Then, redirect to Booking.com to complete the booking or jump to step 4 and 5 if you are integrating a full booking flow.
Book:
- Preview the booking with the order/preview endpoint.
- Use the order/create endpoint to finalise and confirm the booking.
Step 1 - Search for eligible properties
→ Call the accommodations/search endpoint with the following key parameters:
Search request | Description | |
|---|---|---|
| ✓ | "number_of_rooms": 1 |
|
| ✓ | payment.credit_card_required: true |
|
| ✓ | extras: ["products"] |
|
- For Net rates - use the dedicated Affiliate ID provided for your TPI integration in the API calls (Using your regular Affiliate ID may result in authentication errors)
- For Sell rates - use your regular Affiliate ID in the endpoint calls.
Use of filters
You can optionally apply the following filters in your request:
pay_online- payment timing to retrieve only properties with TPI rates (pay_online_lateris not supported for TPI)Note: This may reduce availability since it will only retrieve properties with the cheapest rates.
Other standard search filters such as
checkin,checkoutandcity. See the Filtering guide for examples and best practices.
Example search request
{
"booker": {
"country": "nl",
"platform": "desktop"
},
"checkin": "2025-07-22",
"checkout": "2025-07-25",
"city": -2140479,
"extras": [
"products"
],
"payment": {"timing": "pay_online", "credit_card_required": true },
"guests": {
"number_of_adults": 2,
"number_of_rooms": 1
}
}Identify TPI rates in the search response
The API response returns a list of available TPI rates with the best price for your search criteria (one room, pay online now, etc.)
Look for the following fields to identify them:
Field | Description |
|---|---|
product.id |
|
payment.prepayment_required:true |
|
payment.timings: ["pay_online_now"] |
|
third_party_inventory: true |
|
inventory.type: sell or inventory.type: net |
|
Example - Search response with "Sell" rates
{
"id": 1004657,
"currency": "EUR",
"price": {
"book": 913.06,
"total": 913.06
},
"products": [
{
"id": "tpi-52d4d2944c2739bc83ebb8b57f734850",
"payment": {
"prepayment_required": true,
"timings": ["pay_online_now"]
},
"price": {
"book": 913.06,
"total": 913.06
},
"third_party_inventory": true,
"inventory": {
"third_party": true,
"type": "sell"
}
}
]
}Example - Search response with "Net" rates
Here's an example of a search response with TPI/Net rates:
{
"request_id": "01jwb2mmsg7tc2rn56m8p2pprx",
"data": [
{...},
"products": [
{
"id": "tpi-931a79b7a790d7c3e55ce5029326573c",
"children": [],
"deal": null,
"number_available_at_this_price": 1,
"number_of_adults": 2,
"policies": {
"cancellation": {...},
"meal_plan": {...},
"payment": {
"prepayment_required": true,
"timings": [
"pay_online_now"
]
}
},
"price": {
"book": 745.23,
"total": 745.23
},
"room": 937191701,
"third_party_inventory": true,
"inventory": {
"third_party": true,
"type": "net"
}
}
],
"url": null
},Demand API does not retrieve URLs (or deep link URL) for TPI products in the search response. You will find these in the next step, in the accommodation/availability response.
Step 2 - Find availability and pricing
→ Use the accommodation/availability endpoint for availability and prices in specific properties.
- Include the desired accommodation ID and same details returned from the search request to provide real-time information about availability, rates and applicable policies.
- The response returns a list of available products with TPI rates.
You can check availability for multiple accommodations in a single request using the accommodations/bulk-availability endpoint.
Note that this endpoint currently supports Sell rates only.
Example - Sell rates in availability response
This example shows a product with Sell rate with both, the deep_link_url and url to Booking.com landing page.
{
"request_id": "01j6en0kkx6ve7eyd8nmh6knaz",
"data": {
"id": 2489623,
"currency": "EUR",
"deep_link_url": "booking://hotel/2489623?affiliate_id=1234567&checkin=2025-12-15&checkout=2025-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": "2025-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=2025-12-15&checkout=2025-12-18&no_rooms=1&group_adults=1&selected_currency=EUR"
}
}Example - Net rates availability response
The response includes the list of TPI products with Net rates together with the best_available_price- This field is only included for TPI Net rates.
Refer to the Net rates guide for more details about the best_available_price field.
{
"request_id": "01jwb627s8xa1s24ztkg6acgbe",
"data": {
"id": 547336,
"currency": "EUR",
"deep_link_url": "booking://hotel/547336?affiliate_id=2373042&checkin=2025-07-10&checkout=2025-07-11",
"products": [
{
"id": "tpi-ae0c08d5985957f8bb241f06d0891a81",
"deal": null,
"inventory": {
"third_party": true,
"type": "net"
},
"maximum_occupancy": {
"adults": 2,
"children": null,
"total": 2
},
"number_available_at_this_price": 1,
"policies": {
"cancellation": {
"free_cancellation_until": null,
"schedule": [
{
"from": "now",
"price": 47.33
}
],
"type": "non_refundable"
},
"meal_plan": {...},
"payment": {
"prepayment_required": true,
"timings": [
"pay_online_now"
]
}
},
"price": {
"book": 47.33,
"total": 47.33
},
"best_available_price": {
"total": 52.44
},
"room": 54733603,
"third_party_inventory": true
},
],
"recommendation": null,
"url": "https://www.booking.com/hotel/th/sunchine-paradise-resort.html?aid=2373042&checkin=2025-07-10&checkout=2025-07-11&no_rooms=1&group_adults=2&selected_currency=EUR"
}
}
Step 4 - Display TPI rates in your platform
On Booking.com’s platforms, TPI rates are displayed as “Partner Offer”.
However, to display TPI rates effectively in your platform make sure you adhere to the following terms:
- Do not refer to TPI products as “Third Party Inventory” or “Partner Offer” in your own interface.
- You must agree on a marketing label with your Booking.com Account Manager before going live.
Step 5 - Preview the booking
→ Use the orders/preview endpoint to validate the selected product and retrieve final booking details, including pricing, policies, and payment options.
See the Create orders guide for best practices on constructing your orders/preview request.
Example of orders/preview response
This is an example response from the orders/preview endpoint. It includes cancellation policies, pricing, and third-party inventory indicators.
{
"products": [
{
"id": "1000420_278556531_2_0_0",
"deal": null,
"policies": {
"cancellation": [
{
"from": "now",
"price": {
"accommodation_currency": 0,
"booker_currency": null
}
},
{
"from": "2025-08-22!T22:00:00+00:00",
"price": {
"accommodation_currency": 177.65,
"booker_currency": null
}
}
],
"meal_plan": {
"meals": [],
"plan": "no_plan"
}
},
"price": {
"total": {
"accommodation_currency": 186.92,
"booker_currency": null
}
},
"third_party_inventory": true
}
]
}
Step 6 - Create the order
→ Use the orders/create endpoint, to finalise the booking and initiate the payment process.
Include the correct payment method in your request.
- Net rates - VCC payment.
- Sell rates - Credit Card (or VCC).
A successful response returns key booking identifiers and third-party inventory confirmation and checkin numbers.
Display these fields clearly in your platform confirmation screen and messages.
Example of orders/create response
This orders/create response includes confirmation details, including order, pincode, and third-party inventory identifiers required for guest check-in.
{
"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": "509430129718799",
"pincode": "0000",
"reservation": 12345678,
"third_party_inventory": {
"checkin_number": "123456789",
"confirmation_number": "12345678912345678912"
}
}
}
}
Key response fields
| order |
|
| pincode |
|
| reservation |
|
| checkin_number |
|
| confirmation_number |
|
Example of confirmation message
Example of Booking.com confirmation message for a third-party inventory booking (Partner offer), with pincode, confirmation and checkin number:
Best practices
✓ Always validate bookings with /orders/preview before calling orders/create.
✓ Always show cancellation policies to the user before confirming the booking.
✓ Check that supported payment methods are accepted by the product:
- VCCs for Net rates.
- Credit cards and/or VCC for Commissionable TPI rates.
✓ Display both the checkin_number and confirmation_number on confirmation screens and messages.
Troubleshooting
If TPI rates are not returned in your search or availability requests, this may be due to:
| Issue | Suggested action |
|---|---|
| Multi-room search | Switch to single-room search. |
| You are not onboarded for TPI or using the wrong Affiliate ID | Contact your Booking.com account manager to verify your onboarding status. Use the correct Affiliate ID:
|
extras field missing or not including products | Ensure your request includes extras: ["products"]. |
| 500 error when cancelling | Check if the policy is non-refundable. Check the cancellation policy before using /orders/cancel. |
| Invalid payment method error | Check that your integration supports VCC for Net rates or Credit cards for Sell rates. |
| VCC not accepted | Include credit_card_required:true in the payment object of your request. |
Post booking
For post-booking tasks guidelines on reporting TPI rates, or cancelling TPI bookings, refer to the Post booking dedicated guide.
- Error handling guide - See common client errors, examples and best practices.
- Orders section – Understand how to manage orders, retrieve booking details, and handle cancellations.
- Payments quick guide – Review how
pay_online_now, Credit Cards and VCC work.
Next steps
Learn more about how TPI works across different business models:
