# 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](/demand/docs/development-guide/application-flows#search-look-and-book)), 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 | * Your integration must use Demand API v3.1 (or above)

 |
| ☑ | Authentication | * Sell rates - Use your regular Booking.com Affiliate ID in your requests.
* Net rates - Use a dedicated Affiliate ID provided for net inventory access.

 |
| ☑ | TPI eligibility | * You must be onboarded for TPI rates ([Sell rates](/demand/docs/accommodations/tpi/sell-how-to) or [Net rates](/demand/docs/accommodations/tpi/net-how-to)).

 |


## Step-by-step flow

To support the full booking experience, follow these steps:

End-to-end flow
**Search & look flow:**

1. Search for eligible properties using the [accommodations/search endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/search).
2. Look up availablity, pricing and policies at [accommodations/availability endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/availability).
3. 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:**

1. Preview the booking with the [order/preview endpoint](/demand/docs/open-api/demand-api/orders/orders/preview).
2. Use the [order/create endpoint](/demand/docs/open-api/demand-api/orders/orders/create) to finalise and confirm the booking.


### Step 1 - Search for eligible properties

→ Call the [accommodations/search endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/search) with the following key parameters:

|  | Search request | Description |
|  --- | --- | --- |
| ✓ | `"number_of_rooms": 1` | * Single room - TPI products are only returned for single-room searches (with single or multiple occupancy).

 |
| ✓ | `payment.credit_card_required: true` | * Ensures compatibility with online payment methods (VCC and Cards).

 |
| ✓ | `extras: ["products"]` | * Include products in the response.

 |


Use the correct Affiliate ID
* **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_later` is 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`, `checkout` and `city`. See the [Filtering guide](/demand/docs/accommodations/about-accommodation) for examples and best practices.


#### Example search request


```json
{
  "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` | * The id identifies the product and includes the "tpi" prefix.

 |
| `payment.prepayment_required:true` | * Confirms the product requires upfront payment.

 |
| `payment.timings: ["pay_online_now"]` | * Only this timing is supported.

 |
| `third_party_inventory: true` | * Confirms third-party origin.

 |
| `inventory.type: sell` or `inventory.type: net` | * Identifies the rate type:
  * ["sell" for Commissionable TPI rates](/demand/docs/accommodations/tpi/sell-how-to)
  * ["net" for non-commissionable rates](/demand/docs/accommodations/tpi/net-how-to)

 |


#### Example - Search response with "Sell" rates


```json
{
  "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:


```json
{
  "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 [accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) response.

### Step 2 - Find availability and pricing

→ Use the [accommodations/availability endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) 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.


Bulk availability for Sell rates
You can check availability for multiple accommodations in a single request using the [accommodations/bulk-availability endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/bulk-availability).
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.


```json
{
  "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.

Best available price
Refer to the [Net rates guide](/demand/docs/accommodations/tpi/net-how-to) for more details about the `best_available_price` field.


```json
{
    "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*”.

![TPI rates are presented on the branded landing platforms of Booking.com tagged as “Partner Offer”](/assets/partneroffer.83373d54d22b701c73738c32b76933f75be1d92c23287577be707e890cbf4892.25671134.png)

However, to display TPI rates effectively in your platform make sure you adhere to the following terms:

Displaying TPI rates
- 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](/demand/docs/open-api/demand-api/orders/orders/preview) to validate the selected product and retrieve final booking details, including pricing, policies, and payment options.

See the [Create orders guide](/demand/docs/orders-api/order-preview-create) 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.


```json
{
  "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](/demand/docs/open-api/demand-api/orders/orders/create), to finalise the booking and initiate the payment process.

Include the correct payment method in your request.

- Net rates - [VCC payment](/demand/docs/payments/payments-examples#pay_online_now).
- Sell rates - [Credit Card](/demand/docs/payments/payments-examples2#credit-card--sca-token) (or VCC).


A successful response returns key booking identifiers and third-party inventory confirmation and checkin numbers.

> ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) 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.


```json
{
  "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** | * Booking reference number for cancellations and support.

 |
| **pincode** | * Short identifier often used by travellers and customer service. Included in the confirmation message.

 |
| **reservation** | * Accommodation-specific reservation identifier.

 |
| **checkin_number** | * Specific to TPI bookings - Required for guest check-in at the accommodation.

 |
| **confirmation_number** | * Specific to TPI reservations - 	Used alongside the `pincode` to verify TPI bookings and assist support workflows (e.g, when contacting our Customer Servece support).

 |


#### Example of confirmation message

Example of Booking.com confirmation message for a third-party inventory booking (Partner offer), with pincode, confirmation and checkin number:

![pincode](/assets/confirmation.d7a5e2c72bbd8280111df5cfb31c7eff1a007ed5a8ace385a8d5dd16489efd98.25671134.png)

## Best practices

✓ Always validate bookings with [/orders/preview](/demand/docs/open-api/demand-api/orders/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:* Your regular AID for Sell rates.
* Your dedicated AID for Net rates.

 |
| `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](/demand/docs/open-api/demand-api/orders/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](/demand/docs/accommodations/tpi/reporting-tpi-rates).

References
* [Error handling guide](/demand/docs/support/error-handling/about-errors) - See common client errors, examples and best practices.
* [Orders section](/demand/docs/orders-api/overview) – Understand how to manage orders, retrieve booking details, and handle cancellations.
* [Payments quick guide](/demand/docs/payments/how-to) – Review how `pay_online_now`, Credit Cards and VCC work.


## Next steps

Learn more about how TPI works across different business models: