Historical Reservations API

Use the Historical Reservations API to retrieve reservation and price details for a property, for use in a revenue management system (RMS). Select reservations by check-in date and, optionally, by room reservation status.

The OpenAPI reference describes the request parameters, response fields, and errors. You can download the specification from the reference page to use with your API tooling.

Confirm that your provider account has access to the Historical Reservations API and permission to retrieve reservation history for the property. Authentication alone does not grant access to a property's history. Contact Connectivity Support to confirm the access requirements for your integration.

Use a machine account and obtain an access token as described in token-based authentication. Use a test property that your account is authorized to access when testing your integration.

The production request quota is 250 requests per provider and property in a rolling one-day window. It does not reset at midnight. Requests admitted after authentication consume quota even if a later validation or upstream request fails. Avoid repeated requests for the same interval and immediate retries after a 429 response.

GET https://supply-xml.booking.com/revenue-management-api/properties/{property_id}/historical-reservations

Send the following headers:

This reference describes API version 1.0. Specify it explicitly in the Accept-Version header.

Provide a positive property_id no greater than 2147483647, and both check_in_start and check_in_end query parameters. The request has no body.

The date filters apply to reservation check-in dates. Both boundaries are inclusive. Reservation creation and check-out dates do not restrict the range. A reservation created before the requested period can be returned.

Use date-only values in YYYY-MM-DD format, such as 2026-08-01. Timestamps and timezone suffixes are not accepted. Both parameters are required. The API does not apply a default interval.

The interval must meet all of these conditions:

• The start is earlier than or equal to the end.
• The start is no earlier than today in UTC minus 24 calendar months. When today is 29 February, the 24-month-back date adjusts to 28 February.
• The end is no later than today in UTC. Today is allowed.

The start and end can be the same date to retrieve one check-in day. An ordered range ending after today in UTC returns HTTP 400 with the message Check-in dates must not be in the future (UTC).

The eligibility window uses calendar months. Choose dates within the current window when running examples; a fixed historical example will eventually fall outside that window.

Omit status to include all supported room reservation statuses: OK, CANCELLED, and NO_SHOW. An empty status value returns HTTP 400.

The status filter applies to room reservations. A property reservation is included only when at least one of its room reservations matches. Room reservations that do not match are omitted from that property's reservation group.

Set PROPERTY_ID to an authorized test property and ACCESS_TOKEN to your machine account's access token. Set CHECK_IN_START and CHECK_IN_END to valid YYYY-MM-DD dates in the interval you want to retrieve. Then run:

curl --get \
  "https://supply-xml.booking.com/revenue-management-api/properties/${PROPERTY_ID}/historical-reservations" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Accept: application/json' \
  --header 'Accept-Version: 1.0' \
  --data-urlencode "check_in_start=${CHECK_IN_START}" \
  --data-urlencode "check_in_end=${CHECK_IN_END}"

For a single status, add --data-urlencode 'status=CANCELLED'. See the OpenAPI reference for the parameter format when selecting multiple statuses.

A successful response contains data with the requested property_id and a property_reservations array. Each property reservation contains its matching room_reservations. An empty property_reservations array means no reservations match.

The response uses snake_case field names. Use the field definitions and synthetic response examples in the OpenAPI reference when implementing your parser.

The following synthetic example matches the OpenAPI confirmedAndCancelled example. It is not live property data.

{
  "data": {
    "property_id": 1234567,
    "currency": "EUR",
    "property_reservations": [
      {
        "property_reservation_id": "9876543210",
        "room_reservations": [
          {
            "room_id": "123456701",
            "created_at": "2026-01-15T10:00:00Z",
            "checkin": "2026-02-01",
            "checkout": "2026-02-03",
            "status": "OK",
            "occupancy": {
              "adults": 2,
              "children": 0
            },
            "guest": {
              "total_price": "123.45",
              "price_components": [
                {
                  "description": "room price",
                  "type": "BASE_PRICE",
                  "price": "123.45",
                  "included": true
                },
                {
                  "description": "city tax",
                  "type": "TAX",
                  "price": "10.00",
                  "included": false
                }
              ]
            },
            "hotel": {
              "total_price": "100.00",
              "price_components": [
                {
                  "description": "room price",
                  "type": "BASE_PRICE",
                  "price": "100.00",
                  "included": true
                },
                {
                  "description": "service fee",
                  "type": "FEE",
                  "price": "5.00",
                  "included": false
                }
              ]
            }
          }
        ]
      },
      {
        "property_reservation_id": "9876543211",
        "room_reservations": [
          {
            "room_id": "123456702",
            "created_at": "2026-01-16T10:00:00Z",
            "cancelled_at": "2026-01-17T11:00:00Z",
            "checkin": "2026-02-04",
            "checkout": "2026-02-05",
            "status": "CANCELLED",
            "hotel": {
              "total_price": "80.00",
              "price_components": []
            }
          }
        ]
      }
    ]
  },
  "meta": {
    "ruid": "synthetic-request-id"
  }
}

Field descriptions below match the OpenAPI schemas. Optional fields are omitted when their values were not recorded or are unavailable for this response.

Monetary amounts are decimal strings in the major unit of the response currency. The API limits fractional digits by currency:

These limits include historical currency codes and follow the Connectivity currency rules. They can differ from ISO currency fraction digits.

When an amount has more fractional digits than the currency limit, the API rounds it to the nearest value at that limit. An exact halfway value rounds to the value whose last retained digit is even (HALF_EVEN). Amounts already within the limit keep their fractional digits. The API does not add zero-padding. Values use plain decimal notation, without exponent notation or locale separators.

The following synthetic examples illustrate the rule:

Preserve the returned decimal value when calculating or storing prices.

Some fields are omitted when their values are unavailable. An omitted amount does not mean zero. Read the currency from data.currency. Amounts are decimal strings and do not embed a currency identifier.

Hotel and guest price views can differ. Apply the documented meaning of each price field. The guest view may be absent for net-rate reservations. Treat it independently from hotel.

The supplied total_price is the authoritative figure for each perspective. Totals and components are rounded independently, so their sum may differ. Components have inclusion flags, and some components are absent from the response.

This version does not expose pagination parameters or continuation tokens.

If a request for a period fails or times out while retrieving reservations, try again with a smaller check-in date interval. Use consecutive, non-overlapping whole-day ranges: [A, B], then [B + 1 day, C]. Keep all matching room reservations from each response.

Check the HTTP status and returned error details before retrying. The OpenAPI reference lists the response schemas and supported error codes.

Gateway errors can be JSON or plain text. The Content-Type header indicates which format to parse.

When contacting support, include the request time in UTC, endpoint, HTTP status, error code, and request identifier when present. Do not include your access token or client secret.