{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-connectivity/docs/historical-reservations-api/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Historical Reservations API","siteUrl":"https://developers.booking.com"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"historical-reservations-api","__idx":0},"children":["Historical Reservations API"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Preview reference"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This reference describes API version ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1.0"]},". Contact Connectivity Support to confirm availability and arrange access and testing before integrating. Publication of this reference does not enable access for your provider account or property."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"For revenue management only"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This API is for use in a revenue management system (RMS). It is not a reservation delivery or reservation management API. Historical retrieval does not acknowledge reservation messages. Continue to use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/connectivity/docs/reservations-api/reservations-overview"},"children":["Reservations API"]}," for reservation delivery and acknowledgement."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/connectivity/docs/openapispecs/historical-reservations-api/historical-reservations-api-specification"},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":1},"children":["Before you start"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a machine account and obtain an access token as described in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/connectivity/docs/token-based-authentication"},"children":["token-based authentication"]},". Use a test property that your account is authorized to access when testing your integration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rate-limit","__idx":2},"children":["Rate limit"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," response."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retrieve-historical-reservations","__idx":3},"children":["Retrieve historical reservations"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET https://supply-xml.booking.com/revenue-management-api/properties/{property_id}/historical-reservations\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the following headers:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer {access_token}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Accept"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Accept-Version"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1.0"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This reference describes API version ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1.0"]},". Specify it explicitly in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Accept-Version"]}," header."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Provide a positive ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["property_id"]}," no greater than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2147483647"]},", and both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["check_in_start"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["check_in_end"]}," query parameters. The request has no body."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"choose-the-check-in-date-interval","__idx":4},"children":["Choose the check-in date interval"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The date filters apply to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use date-only values in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]}," format, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2026-08-01"]},". Timestamps and timezone suffixes are not accepted. Both parameters are required. The API does not apply a default interval."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The interval must meet all of these conditions:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The start is earlier than or equal to the end."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The end is no later than today in UTC. Today is allowed."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," with the message ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Check-in dates must not be in the future (UTC)"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"filter-by-status","__idx":5},"children":["Filter by status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," to include all supported room reservation statuses: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OK"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NO_SHOW"]},". An empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," value returns HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request","__idx":6},"children":["Example request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PROPERTY_ID"]}," to an authorized test property and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCESS_TOKEN"]}," to your machine account's access token. Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHECK_IN_START"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHECK_IN_END"]}," to valid ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]}," dates in the interval you want to retrieve. Then run:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --get \\\n  \"https://supply-xml.booking.com/revenue-management-api/properties/${PROPERTY_ID}/historical-reservations\" \\\n  --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n  --header 'Accept: application/json' \\\n  --header 'Accept-Version: 1.0' \\\n  --data-urlencode \"check_in_start=${CHECK_IN_START}\" \\\n  --data-urlencode \"check_in_end=${CHECK_IN_END}\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a single status, add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--data-urlencode 'status=CANCELLED'"]},". See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/connectivity/docs/openapispecs/historical-reservations-api/historical-reservations-api-specification"},"children":["OpenAPI reference"]}," for the parameter format when selecting multiple statuses."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"understand-the-response","__idx":7},"children":["Understand the response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful response contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," with the requested ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["property_id"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["property_reservations"]}," array. Each property reservation contains its matching ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["room_reservations"]},". An empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["property_reservations"]}," array means no reservations match."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["snake_case"]}," field names. Use the field definitions and synthetic response examples in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/connectivity/docs/openapispecs/historical-reservations-api/historical-reservations-api-specification"},"children":["OpenAPI reference"]}," when implementing your parser."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-response","__idx":8},"children":["Example response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following synthetic example matches the OpenAPI ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmedAndCancelled"]}," example. It is not live property data."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"data\": {\n    \"property_id\": 1234567,\n    \"currency\": \"EUR\",\n    \"property_reservations\": [\n      {\n        \"property_reservation_id\": \"9876543210\",\n        \"room_reservations\": [\n          {\n            \"room_id\": \"123456701\",\n            \"created_at\": \"2026-01-15T10:00:00Z\",\n            \"checkin\": \"2026-02-01\",\n            \"checkout\": \"2026-02-03\",\n            \"status\": \"OK\",\n            \"occupancy\": {\n              \"adults\": 2,\n              \"children\": 0\n            },\n            \"guest\": {\n              \"total_price\": \"123.45\",\n              \"price_components\": [\n                {\n                  \"description\": \"room price\",\n                  \"type\": \"BASE_PRICE\",\n                  \"price\": \"123.45\",\n                  \"included\": true\n                },\n                {\n                  \"description\": \"city tax\",\n                  \"type\": \"TAX\",\n                  \"price\": \"10.00\",\n                  \"included\": false\n                }\n              ]\n            },\n            \"hotel\": {\n              \"total_price\": \"100.00\",\n              \"price_components\": [\n                {\n                  \"description\": \"room price\",\n                  \"type\": \"BASE_PRICE\",\n                  \"price\": \"100.00\",\n                  \"included\": true\n                },\n                {\n                  \"description\": \"service fee\",\n                  \"type\": \"FEE\",\n                  \"price\": \"5.00\",\n                  \"included\": false\n                }\n              ]\n            }\n          }\n        ]\n      },\n      {\n        \"property_reservation_id\": \"9876543211\",\n        \"room_reservations\": [\n          {\n            \"room_id\": \"123456702\",\n            \"created_at\": \"2026-01-16T10:00:00Z\",\n            \"cancelled_at\": \"2026-01-17T11:00:00Z\",\n            \"checkin\": \"2026-02-04\",\n            \"checkout\": \"2026-02-05\",\n            \"status\": \"CANCELLED\",\n            \"hotel\": {\n              \"total_price\": \"80.00\",\n              \"price_components\": []\n            }\n          }\n        ]\n      }\n    ]\n  },\n  \"meta\": {\n    \"ruid\": \"synthetic-request-id\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-fields","__idx":9},"children":["Response fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Field descriptions below match the OpenAPI schemas. Optional fields are omitted when their values were not recorded or are unavailable for this response."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reservation data for the requested property. Optional values are omitted when unavailable, rather than returned as null."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.property_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Booking.com property ID requested in the path."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.currency"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Currency code for all monetary amounts in the response, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EUR"]},". The field is absent when unavailable."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.property_reservations"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Property reservations with matching room reservations. Empty when no eligible room reservations match the check-in range and status filter."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["property_reservation_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Booking.com property reservation identifier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["room_reservations"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Matching room reservations. Rooms outside the check-in date range or excluded by the status filter are omitted. The entire property reservation is omitted if no rooms match."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["room_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Booking.com room product identifier. This identifies the booked room type, not the specific reservation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reservation creation timestamp in UTC. This field reflects when the reservation was created and is not a query filter."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancellation timestamp in UTC when available. Omitted when unavailable."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkin"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check-in date."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check-out date."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Room reservation status: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OK"]}," for confirmed reservations, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]}," for cancellations, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NO_SHOW"]}," for no-shows."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["occupancy"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Guest counts when available. Each count is independently optional. Counts that were not recorded are omitted. The object is omitted when neither count is available."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["occupancy.adults"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of adults, when known."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["occupancy.children"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of children, when known. An explicit zero means no children."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["guest"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Guest price perspective. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total_price"]}," is the reservation total value. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["included"]}," indicates whether a component is part of that total. This object and its price components are omitted for net-rate reservations."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hotel"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Property price perspective. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total_price"]}," is the total net room price; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["included"]}," indicates whether a component is included in the room rate. This required object can differ from the guest price perspective."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total_price"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Total amount for this perspective, as a major-unit decimal string in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.currency"]},". The supplied total is authoritative and need not equal the sum of returned components. See ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["guest"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hotel"]}," for the meaning of each total."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["price_components"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Available price components. The array can be empty."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable component description."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Component category: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FEE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BASE_PRICE"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TAX"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["price"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Component amount as a major-unit decimal string in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.currency"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["included"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inclusion indicator for this price perspective. See ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["guest"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hotel"]}," for its meaning."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Metadata for support and request tracing."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ruid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request unique identifier. Include it when contacting Connectivity support."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"interpret-price-details","__idx":10},"children":["Interpret price details"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Monetary amounts are decimal strings in the major unit of the response currency. The API limits fractional digits by currency:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Maximum fractional digits"},"children":["Maximum fractional digits"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Currency codes"},"children":["Currency codes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["0"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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, XPF"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BHD, IQD, JOD, KWD, LYD, OMR, TND"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All other currency codes"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These limits include historical currency codes and follow the Connectivity currency rules. They can differ from ISO currency fraction digits."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following synthetic examples illustrate the rule:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Currency"},"children":["Currency"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Amount before rounding"},"children":["Amount before rounding"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Returned decimal string"},"children":["Returned decimal string"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["EUR"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2.665"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"2.66\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["EUR"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2.675"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"2.68\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["EUR"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["12.3"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"12.3\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JPY"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1526.99"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"1527\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["IDR"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-12.9"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"-13\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BHD"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1.2345"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"1.234\""]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Preserve the returned decimal value when calculating or storing prices."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some fields are omitted when their values are unavailable. An omitted amount does not mean zero. Read the currency from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.currency"]},". Amounts are decimal strings and do not embed a currency identifier."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hotel and guest price views can differ. Apply the documented meaning of each price field. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["guest"]}," view may be absent for net-rate reservations. Treat it independently from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hotel"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The supplied ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-size-and-pagination","__idx":11},"children":["Response size and pagination"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This version does not expose pagination parameters or continuation tokens."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[A, B]"]},", then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[B + 1 day, C]"]},". Keep all matching room reservations from each response."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":12},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the HTTP status and returned error details before retrying. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/connectivity/docs/openapispecs/historical-reservations-api/historical-reservations-api-specification"},"children":["OpenAPI reference"]}," lists the response schemas and supported error codes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Gateway errors can be JSON or plain text. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]}," header indicates which format to parse."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Response"},"children":["Response"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to check"},"children":["What to check"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required query parameters, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]}," date format, interval bounds, property ID, and status values."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication credentials and token expiry. Obtain a valid token before retrying."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether your provider is authorized to retrieve history for the requested property."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request quota. Avoid immediate repeated retries."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["502"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A service or upstream failure. If the request failed while retrieving reservations, try a smaller check-in date interval. If the issue persists, contact Connectivity Support."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The gateway or an upstream service is temporarily unavailable. Retry with backoff; contact Connectivity Support if the issue persists."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["504"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The gateway or an upstream service timed out. Try a smaller check-in date interval and avoid repeatedly retrying the full range. No fixed interval guarantees completion."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},"headings":[{"value":"Historical Reservations API","id":"historical-reservations-api","depth":1},{"value":"Before you start","id":"before-you-start","depth":2},{"value":"Rate limit","id":"rate-limit","depth":2},{"value":"Retrieve historical reservations","id":"retrieve-historical-reservations","depth":2},{"value":"Choose the check-in date interval","id":"choose-the-check-in-date-interval","depth":3},{"value":"Filter by status","id":"filter-by-status","depth":3},{"value":"Example request","id":"example-request","depth":3},{"value":"Understand the response","id":"understand-the-response","depth":2},{"value":"Example response","id":"example-response","depth":3},{"value":"Response fields","id":"response-fields","depth":3},{"value":"Interpret price details","id":"interpret-price-details","depth":3},{"value":"Response size and pagination","id":"response-size-and-pagination","depth":3},{"value":"Troubleshooting","id":"troubleshooting","depth":2}],"frontmatter":{"excludeFromSearch":true,"sidebar":{"path":"sidebars.yaml"},"title":"Historical Reservations API","description":"Retrieve historical reservation and price details for a property using check-in dates and optional reservation status filters.","keywords":{"includes":["historical reservations","revenue management","RMS","check_in_start","check_in_end"]},"seo":{"title":"Historical Reservations API"}},"lastModified":"2026-10-29T14:02:26.954Z","pagePropGetterError":{"message":"","name":""}},"slug":"/connectivity/docs/historical-reservations-api/overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}