Retrieve a property's historical reservation details to initialise or reconcile reservation data for revenue management. Room reservations are selected by creation timestamp and optionally by status, and responses carry stay dates, available occupancy and guest and property price perspectives. Preview reference for version 1.0; access requires a connection authorised to read the property's reservation history.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/booking-com:booking-com-historical-reservations-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Historical reservations API
description: Preview reference for API version 1.0.
version: 1.0.0
contact:
name: Connectivity Team
url: https://connect.booking.com
email: connectivity@booking.com
license:
name: Copyright Booking.com. All rights reserved.
url: https://www.booking.com
servers:
- url: https://supply-xml.booking.com
description: Intended production API gateway; confirm availability and access before use
security:
- BearerAuth: []
tags:
- name: Historical reservations
description: Retrieve historical reservation data for an authorized property.
paths:
/revenue-management-api/properties/{property_id}/historical-reservations:
get:
tags:
- Historical reservations
summary: Retrieve historical reservations
description: Retrieve eligible room reservations created within the inclusive UTC range, grouped by property reservation. The range selects reservation creation timestamps, not check-in or check-out dates. Both bounds are required. The endpoint returns confirmed, cancelled, and no-show reservations and supports an optional room status filter. It does not expose pagination or a continuation token. Optional response fields are omitted when unavailable; an omitted value does not mean zero.
operationId: getHistoricalReservations
parameters:
- name: property_id
in: path
required: true
description: Booking.com property ID for a property your connection is authorized to access for reservation history.
schema:
type: integer
format: int32
minimum: 1
maximum: 2147483647
examples:
property:
summary: Example property ID
value: 1234567
- name: created_at_start
in: query
required: true
description: Inclusive reservation-creation lower bound in UTC. Use an ISO 8601 timestamp ending in Z, for example 2026-01-01T00:00:00Z. This value must be on or after the current UTC time minus 24 calendar months and must not be after created_at_end. There is no default. Choose dates within the current eligibility window; fixed examples eventually expire.
schema:
type: string
format: date-time
examples:
start:
summary: Start of the example creation range
value: '2026-01-01T00:00:00Z'
- name: created_at_end
in: query
required: true
description: Inclusive reservation-creation upper bound in UTC. Use an ISO 8601 timestamp ending in Z. This value must not be in the future. created_at_start must be on or after created_at_end minus 24 calendar months. Calendar subtraction adjusts a leap day to the final valid day of February. There is no default.
schema:
type: string
format: date-time
examples:
end:
summary: End of the example creation range
value: '2026-01-31T23:59:59Z'
- name: status
in: query
required: false
style: form
explode: true
description: Room reservation statuses to include. Omit this parameter to include all supported statuses. Repeat the parameter to select multiple statuses, for example status=OK&status=NO_SHOW. Only matching rooms remain in each property reservation; property reservations without matching rooms are omitted.
schema:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/ReservationStatus'
examples:
confirmed:
summary: Confirmed reservations
value:
- OK
confirmedAndNoShow:
summary: Confirmed and no-show reservations
value:
- OK
- NO_SHOW
- name: Accept-Version
in: header
required: false
description: API version. Send 1.0; this is also the default when the header is omitted.
schema:
type: string
enum:
- '1.0'
default: '1.0'
examples:
version:
summary: API version
value: '1.0'
responses:
'200':
description: Historical reservations matching the request. The response has no pagination parameters or continuation token.
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalReservationsResponse'
examples:
confirmedAndCancelled:
summary: Confirmed and cancelled reservations
value:
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
description: Synthetic data showing both price perspectives, an explicit zero child count, and a cancelled reservation without optional guest or occupancy data.
noShows:
summary: No-show reservation with partial occupancy
value:
data:
property_id: 1234567
currency: EUR
property_reservations:
- property_reservation_id: '9876543212'
room_reservations:
- room_id: '123456701'
created_at: '2026-01-15T12:00:00Z'
checkin: '2026-02-03'
checkout: '2026-02-05'
status: NO_SHOW
occupancy:
adults: 1
hotel:
total_price: '100.00'
price_components: []
meta:
ruid: synthetic-request-id
description: Synthetic data for status=NO_SHOW. The omitted children count is unknown; it does not mean zero.
noMatches:
summary: No matching reservations
value:
data:
property_id: 1234567
property_reservations: []
meta:
ruid: synthetic-request-id
'400':
description: A required parameter is missing or invalid, including an invalid property ID, timestamp, creation range, or status.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceErrorResponse'
examples:
invalidRequest:
summary: Request parameters are missing or invalid
value:
errors:
- code: INVALID_REQUEST_PARAMETERS
message: Request parameters are missing or invalid
meta:
ruid: synthetic-request-id
'401':
description: Authentication is missing, invalid, or expired. Obtain a valid Connectivity token and send it in the Authorization header. Gateway authentication error codes and messages can differ from the service example.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceErrorResponse'
examples:
serviceAuthenticationRequired:
summary: Authentication required
value:
errors:
- code: UNAUTHORIZED
message: Authentication is required
meta:
ruid: synthetic-request-id
'403':
description: Access to the requested property is not permitted. Check that your connection includes permission to read reservation history.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceErrorResponse'
examples:
propertyAccessDenied:
summary: Access to this property is not permitted
value:
errors:
- code: FORBIDDEN
message: Access to this property is not permitted
meta:
ruid: synthetic-request-id
'429':
description: The API gateway rejected the request because a rate limit was exceeded. The production quota is 25 requests per provider and property in a rolling one-day window. Wait before retrying and reduce the request frequency. Quota errors can use a different gateway body from the service errors shown for other responses.
content:
application/json:
schema:
description: Gateway error response. The body depends on which rate-limiting policy rejected the request.
'500':
description: An unexpected error occurred while processing the request. Retain the request identifier when contacting support.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceErrorResponse'
examples:
unexpectedError:
summary: An unexpected error occurred
value:
errors:
- code: INTERNAL_SERVER_ERROR
message: An unexpected error occurred
meta:
ruid: synthetic-request-id
'502':
description: Authorization or historical reservation data is temporarily unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceErrorResponse'
examples:
authorizationUnavailable:
summary: Authorization service is temporarily unavailable
value:
errors:
- code: AUTHORIZATION_SERVICE_ERROR
message: Authorization service is temporarily unavailable
meta:
ruid: synthetic-request-id
reservationsUnavailable:
summary: Historical reservations are temporarily unavailable
value:
errors:
- code: UPSTREAM_SERVICE_ERROR
message: Historical reservations are temporarily unavailable
meta:
ruid: synthetic-request-id
default:
description: Other API gateway errors. Gateway responses can differ from the service error body. Check the HTTP status and retain any request identifier supplied.
components:
schemas:
ServiceErrorResponse:
type: object
description: An error returned while processing the historical reservations request.
properties:
errors:
type: array
description: One or more errors.
items:
$ref: '#/components/schemas/ApiError'
minItems: 1
meta:
$ref: '#/components/schemas/RequestMetadata'
required:
- errors
- meta
ReservationStatus:
type: string
description: 'Room reservation status: OK for confirmed reservations, CANCELLED for cancellations, and NO_SHOW for no-shows.'
enum:
- OK
- CANCELLED
- NO_SHOW
RoomReservation:
type: object
description: Reservation details for a room. Dates of stay are separate from the reservation creation timestamp used to select records.
properties:
room_id:
type: string
description: Booking.com room product identifier. This identifies the booked room type; it is not a unique room-reservation identifier.
minLength: 1
created_at:
type: string
description: Reservation creation timestamp in UTC.
format: date-time
cancelled_at:
type: string
description: Cancellation timestamp in UTC when available. Omitted when unavailable; a cancelled or no-show reservation can omit this field.
format: date-time
checkin:
type: string
description: Check-in date.
format: date
checkout:
type: string
description: Check-out date.
format: date
status:
$ref: '#/components/schemas/ReservationStatus'
occupancy:
description: Guest counts when available. Omitted when unavailable. An absent count does not mean zero.
allOf:
- $ref: '#/components/schemas/Occupancy'
guest:
description: Guest price perspective. total_price is the reservation total value; included indicates whether a component is included in that total. This object is omitted when the guest price perspective is unavailable, including reservations with guest price markup.
allOf:
- $ref: '#/components/schemas/ReservationPrice'
hotel:
description: Property price perspective. total_price is the total net room price; included indicates whether a component is included in the room rate. This required object can differ from the guest price perspective.
allOf:
- $ref: '#/components/schemas/ReservationPrice'
required:
- room_id
- created_at
- checkin
- checkout
- status
- hotel
PropertyReservation:
type: object
description: A property reservation grouping one or more matching room reservations.
properties:
property_reservation_id:
type: string
description: Booking.com property reservation identifier.
minLength: 1
room_reservations:
type: array
description: Matching room reservations. Rooms excluded by the status filter are omitted; the entire property reservation is omitted if no rooms match.
items:
$ref: '#/components/schemas/RoomReservation'
minItems: 1
required:
- property_reservation_id
- room_reservations
RequestMetadata:
type: object
description: Metadata for support and request tracing.
properties:
ruid:
type: string
description: Request unique identifier. Include it when contacting Connectivity support.
required:
- ruid
HistoricalReservationsData:
type: object
description: Reservation data for the requested property. Optional values are omitted when unavailable, rather than returned as null.
properties:
property_id:
type: integer
format: int32
minimum: 1
maximum: 2147483647
description: The Booking.com property ID requested in the path.
currency:
type: string
description: Currency code for the monetary amounts, for example EUR. Omitted when unavailable; do not infer a currency when this field is absent.
property_reservations:
type: array
description: Property reservations with matching room reservations. Empty when no eligible room reservations match the creation range and status filter.
items:
$ref: '#/components/schemas/PropertyReservation'
required:
- property_id
- property_reservations
PriceComponent:
type: object
description: One base-price, fee, or tax component.
properties:
description:
type: string
description: Human-readable component description.
minLength: 1
type:
type: string
description: Component category.
enum:
- FEE
- BASE_PRICE
- TAX
price:
type: string
description: Component amount as a major-unit decimal string in data.currency, rounded only when it exceeds the currency limit. Uses the currency limits and HALF_EVEN rule described in ReservationPrice; shorter scales are preserved without zero-padding. For example, JPY 1526.99 becomes "1527", IDR -12.9 becomes "-13", and BHD 1.2345 becomes "1.234".
minLength: 1
included:
type: boolean
description: For guest components, whether the amount is included in the reservation total value. For hotel components, whether it is included in the room rate.
required:
- description
- type
- price
- included
ApiError:
type: object
description: Details of an error.
properties:
code:
type: string
description: Machine-readable error code.
message:
type: string
description: Human-readable error description.
required:
- code
- message
Occupancy:
type: object
description: Known guest counts. Each count is independently optional and is omitted when unknown.
properties:
adults:
type: integer
format: int32
minimum: 0
description: Number of adults, when known.
children:
type: integer
format: int32
minimum: 0
description: Number of children, when known. An explicit zero means no children.
HistoricalReservationsResponse:
type: object
description: Historical reservations and metadata for this request.
properties:
data:
$ref: '#/components/schemas/HistoricalReservationsData'
meta:
$ref: '#/components/schemas/RequestMetadata'
required:
- data
- meta
ReservationPrice:
type: object
description: 'Monetary values for one price perspective, as major-unit decimal strings in data.currency. The Connectivity currency limits are 0 fractional digits for AFA, BIF, BYR, CLP, COP, DJF, ECS, GNF, HUF, IDR, ISK, JPY, KMF, KRW, LAK, MGA, MZM, PYG, RWF, TJR, TMM, TWD, UGX, VND, VUV, XAF, XOF and XPF; 3 for BHD, IQD, JOD, KWD, LYD, OMR and TND; and 2 for all other currency codes. These limits include historical currency codes and can differ from ISO currency fraction digits. When an amount has more fractional digits than the currency limit, the amount is rounded to drop the excess digits, to the nearest value, with exact halfway values rounded to the value whose last retained digit is even (HALF_EVEN). Shorter scales are preserved without zero-padding. Values use plain decimal notation without exponents or locale separators. Preserve the returned decimal value. Use the supplied total instead of reconstructing it by summing components: totals and components are rounded independently, components have inclusion flags, and some component categories are omitted.'
properties:
total_price:
type: string
description: Total amount for this perspective, as a major-unit decimal string in data.currency. When an amount has more fractional digits than the currency limit, the amount is rounded to drop the excess digits using the currency limits and HALF_EVEN rule described in ReservationPrice; shorter scales are preserved. For example, EUR 2.665 becomes "2.66", EUR 2.675 becomes "2.68", and EUR 12.3 stays "12.3". The supplied total is authoritative and need not equal the sum of returned components. See guest and hotel for the meaning of each total.
minLength: 1
price_components:
type: array
description: Available price components. The array can be empty. Markup components are omitted, and hotel components omit deposits.
items:
$ref: '#/components/schemas/PriceComponent'
required:
- total_price
- price_components
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Use a Connectivity API token obtained through token-based authentication. Send `Authorization: Bearer {token}`. Your connection must be authorized to read reservation history for the requested property.'
externalDocs:
description: Historical Reservations API guide
url: https://developers.booking.com/connectivity/docs/historical-reservations-api/overview
x-tagGroups:
- name: API Endpoints
tags:
- Historical reservations
- name: Documentation
tags:
- About Try it