Sell rates quick guide

This guide explains how to retrieve third-party accommodation with special sell rates through our API, so you can provide more competitive prices. Find here step-by-step instructions to integrate this feature, including setting up API requests, handling responses, and using Sell rates effectively in your platform.

Retrieving sell rates

To retrieve sell rates for accommodations from a third-party inventory, start making API calls to the accommodations/search endpoint.

The process for retrieving sell rates involves defining search parameters, filtering results, and checking for the appropriate fields in the response.

Step 1 - Making API calls with key parameters

When making an API call to retrieve sell rates, follow these guidelines:

Example search request:

To retrieve Sell rates, use the accommodations/search endpoint with the following parameters:

{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2025-05-22",
  "checkout": "2025-05-25",
  "city": -2140479,
  "extras": [
    "products"
  ],
  "payment": {"timing": "pay_online", "credit_card_required": true },
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}

Step 2 - Handling API responses

Once you send the search request, the response contains the third-party inventory accommodation and associated details.

Key response parameters

Look for the following key parameters in the response:

Example search response

Here's an example of a 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"
      }
    }
  ]
}

Making sell rates bookable

Depending on the sort of integration you are implementing, follow the dedicated processes to make sell rates bookable.

Search and look

This sort of integration requires performing the Look and book part of the flow using whitelabel.

In these cases, you receive the sell rates on the branded landing platforms of Booking.com tagged as “Partner Offer” in our user interface.

You can then market this using the whitelabel setup.

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.

This includes handling responses at every step.

Prerequisites

To enjoy the benefits of sell rates, you must first meet these requirements:

Steps

In each step, identify whether a product comes from a third-party inventory and offers Sell rates by checking the inventory object and the third_party_inventory field.

Step 1- Search for third-party inventory properties

Search for available properties using the accommodation/search endpoint.

Step 2 - 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.

The response returns a list of available products with the best price for your search criteria (one room, pay online now, etc.)

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

Step 3 - Preview the booking

For the booking, you need to use the order/preview endpoint first.

In the response you can see the order details, including price breakdown and available payment methods.

Example of orders/preview response

{
  "products": [
    {
      "id": "tpi-e4eb119953928affbd8f247d9b2ccb24",
      "deal": null,
      "policies": {...},
      "price": {...},
      "room": 0,
      "third_party_inventory": true,
      "inventory": {
        "third_party": true,
        "type": "sell"
      }
    }
  ]
}

Step 4 - 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.

Successful order response

A successful order/create response returns the receipt URL, but also the following ids:

As this is an accommodation provided by a third party inventory, the order response also includes the third_party_inventory object with:

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": "509430129718799",
    "pincode": "0000",
    "reservation": 12345678,
    "third_party_inventory": {
      "checkin_number": "123456789",
      "confirmation_number": "12345678912345678912"
    }
  }
}

Example of confirmation message for a third-party inventory booking (Partner offer), with confirmation id, checkin number and pin code:

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:

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.