Retrieve Reservations
This endpoint is used to retrieve reservations via pagination.
-
Request
GET https://app.hotelrunner.com/api/v2/apps/reservations
// Example Request Snippet for JavaScript XHR var data = null; var xhr = new XMLHttpRequest(); xhr.withCredentials = true; xhr.addEventListener("readystatechange", function () { if (this.readyState === 4) { console.log(this.responseText); } }); xhr.open("GET", "https://app.hotelrunner.com/api/v2/apps/reservations?token={TOKEN}&hr_id={HR_ID}"); xhr.setRequestHeader("cache-control", "no-cache"); xhr.send(data);
The above command returns JSON structured like this:
{
"reservations": [
{
"reservation_id": 37515739,
"hr_number": "R377873409",
"provider_number": null,
"pms_number": null,
"channel": "online",
"channel_display": "Online",
"source_display": null,
"state": "reserved",
"modified": false,
"total_guests": 3,
"total_rooms": 1,
"guest": "John Doe",
"firstname": "John",
"lastname": "Doe",
"country": "TR",
"guest_national_id": "12345678910",
"guest_is_citizen": true,
"cancel_reason": null,
"completed_at": "2026-02-23T16:28:12.000+03:00",
"updated_at": "2026-02-23T16:32:20.000+03:00",
"sub_total": 110.0,
"extras_total": 20.0,
"adjustments_total": -0.0,
"tax_total": 13.928,
"item_total": "130.0",
"total": 130.0,
"currency": "USD",
"checkin_date": "2026-02-23",
"checkout_date": "2026-02-25",
"note": "Baby crib",
"payment": "cash",
"payment_details": null,
"paid_amount": 13.0,
"pms_version_generated": true,
"address": {
"city": "Cesme",
"state": "35",
"country": "Turkey (TR)",
"country_code": "TR",
"phone": "5555555555",
"email": "john@hotelrunner.com",
"street": "Cesme Mh. Cesme Cd. No:1",
"street_2": "",
"postal_code": "36040"
},
"billing_address": {
"bill_type": null,
"city": "Izmir",
"state": "Izmir",
"country": "Turkey",
"country_code": "TR",
"phone": "+905555555555",
"email": "john@hotelrunner.com",
"street": "Cesme",
"street_2": "",
"tax_office": "",
"tax_id": "",
"company": "",
"firstname": "John",
"lastname": "Doe"
},
"extra_adjustments_details": [],
"adjustment_details": [],
"price_adjustments_details": [],
"next_states": [
"confirm"
],
"system_message": null,
"system_url": "http://testhotel.hotelrunner.com/admin/orders/R377873409",
"deposit_tax_inclusive": true,
"requires_response": true,
"cancelation_policy": [],
"rooms": [
{
"id": 32924103,
"state": "reserved",
"code": "HR:823753",
"number": null,
"voucher_number": "R377873409",
"availability_group": "HR:823753",
"rate_code": "HR:823753",
"rate_plan_code": "HR:823753",
"inv_code": "HR:823753",
"non_refundable": false,
"price": 110.0,
"total": 130.0,
"nights": 2,
"meal_plan": "bed-breakfast",
"meal_plan_presentation": "Bed and breakfast",
"total_guest": 3,
"total_adult": 2,
"child_ages": [
1
],
"name": "Family Room",
"name_presentation": "Family Room",
"checkin_date": "2026-02-23",
"checkout_date": "2026-02-25",
"extra_info": "",
"daily_prices": [
{
"date": "2026-02-23",
"price": 55.0,
"original_price": 55.0,
"discount": 0.0,
"rate_code": "HR:823753",
"version": "v2"
},
{
"date": "2026-02-24",
"price": 55.0,
"original_price": 55.0,
"discount": 0.0,
"rate_code": "HR:823753",
"version": "v2"
}
],
"extras": [
{
"name": "Airport Transfer",
"price": 20.0,
"base_price": "20.0",
"code": "",
"promotions_total": "0.0",
"is_extra": true,
"total": 20.0,
"quantity": 1,
"dates": {},
"repeat_type": "first_night"
},
{
"name": "VAT10 (10.0% Included in price)",
"price": 11.607999999999999,
"included_in_price": true
},
{
"name": "VAT2 (2.0% Included in price)",
"price": 2.3209999999999997,
"included_in_price": true
}
],
"updated_at": "2026-02-23T16:26:42.000+03:00",
"meta": {},
"extras_total": 20.0,
"fixed_adjustments_total": 0.0,
"included_taxes_total": 13.928999999999998,
"excluded_fees_and_taxes_total": 0.0,
"cancelation_refund_total": 0.0,
"cancelation_refund_tax_type": "exclusive",
"cancelation_penalty_total": 0.0,
"cancelation_penalty_tax_type": "inclusive",
"promotions_total": 0.0,
"room_base_price": 110.0,
"room_sub_total": 130.0,
"comments": [
{
"body": "Baby crib",
"channel_note": false,
"housekeeping": null,
"guest_visible": true
}
]
}
],
"payments": [
{
"state": "checkout",
"id": 34909131,
"amount": "130.0",
"currency": "USD",
"exchanged_amount": "130.0",
"exchange_currency": "USD",
"exchange_rate": "0.0",
"paid_at": null,
"payment_method_name": "Pay at the hotel",
"payment_method": "cash",
"installment": 0,
"response_code": null
},
{
"state": "completed",
"id": 34909219,
"amount": "13.0",
"currency": "USD",
"exchanged_amount": "13.0",
"exchange_currency": "USD",
"exchange_rate": "0.0",
"paid_at": "2026-02-23T16:32:20.000+03:00",
"payment_method_name": "Pay at the hotel",
"payment_method": "cash",
"installment": 0,
"response_code": null
}
],
"meta_data_conversions": [],
"channel_profile_data_conversions": null,
"integration_echo_details": null,
"message_uid": "cc90fb5160e2ea7b7f4c493b9e8ec88d"
}
],
"count": 1,
"current_page": 1,
"pages": 1
}
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| from_date | 10 days before | No | Format: YYYY-MM-DD. If provided, reservations that were created after this date will be retrieved. (Max: 30 days before) |
| from_last_update_date | - | No | Format: YYYY-MM-DD. If provided, reservations that were updated after this date will be retrieved. |
| per_page | 10 | No | Number of reservations per page. |
| page | 1 | No | Number of current page. (Use this parameter only with 'undelivered=false' parameter) |
| reservation_number | - | No | Used to get a specific reservation. It can be either HotelRunner or Channel reservation code. |
| undelivered | true | No | By default, HotelRunner returns only undelivered reservations in response. |
| modified | false | No | If set to true, HotelRunner will return only modified reservations. |
| booked | false | No | If set to true, HotelRunner will return only new reservations. |
Reservation Object
| Name | Description |
|---|---|
| reservation_id | Unique reservation ID on HotelRunner |
| hr_number | Reservation code on HotelRunner |
| provider_number | Reservation code on Sales Channel (can be blank*) |
| pms_number | Reservation code generated by PMS (can be blank*) |
| channel | Sales channel code |
| channel_display | Sales channel name |
| source_display | Source channel display name (can be blank*) |
| state | Reservation status on HotelRunner (reserved,confirmed,canceled)* |
| modified | Indicates that whether the reservation has been modified after the creation |
| total_guests | Total number of guests in the reservation |
| total_rooms | Total number of rooms in the reservation |
| guest | Guest name, who made the reservation |
| firstname | Guest first name |
| lastname | Guest last name |
| country | Guest country code |
| guest_national_id | Guest national ID (can be blank*) |
| guest_is_citizen | Indicates whether the guest is citizen of property country |
| cancel_reason | Cancel reason (can be blank*) |
| completed_at | The time that shows when HotelRunner received the reservation (ISO-8601) |
| updated_at | The time that shows when HotelRunner received the latest update (ISO-8601) |
| sub_total | Sub total (excluding taxes and extras) |
| extras_total | Extras total (tax not included) |
| adjustments_total | Adjustments total (Price adjustments total that made by Property Admin) |
| tax_total | Tax total |
| item_total | Total amount before final adjustments |
| total | Grand total |
| currency | Currency (ISO-4217) |
| checkin_date | Check-in Date |
| checkout_date | Check-out Date |
| note | Guest note (can be blank*) |
| payment | Payment method information (credit_card, bank_transfer, cash, paypal) |
| payment_details | Additional payment details (can be blank*) |
| paid_amount | Paid amount |
| pms_version_generated | Indicates whether the PMS compatible reservation version is generated |
| requires_response | Indicates the ability of a PMS that can be able to send state updates or not |
| deposit_tax_inclusive | Indicates whether deposit includes taxes |
| address | See address json structure |
| billing_address | See billing_address json structure |
| extra_adjustments_details | Detailed information about extra adjustments (can be empty) |
| adjustment_details | Detailed information about adjustments (can be empty) |
| price_adjustments_details | Detailed information about price adjustments (can be empty) |
| cancelation_policy | Cancellation policy rules applied to the reservation |
| rooms | See rooms json structure |
| payments | See payments json structure |
| meta_data_conversions | Metadata conversion details (can be empty) |
| integration_echo_details | Integration echo details (can be blank*) |
| message_uid | Unique message identifier |
Address
| Name | Description |
|---|---|
| address > city | Guest city |
| address > state | Guest state or province |
| address > country | Guest country name |
| address > country_code | Guest country code (ISO-3166) |
| address > phone | Guest phone number |
| address > email | Guest email address |
| address > street | Guest street address |
| address > street_2 | Additional address information (can be blank*) |
| address > postal_code | Postal code of the guest address |
Billing Address
| Name | Description |
|---|---|
| billing_address > bill_type | Billing type (can be blank*) |
| billing_address > city | Billing city |
| billing_address > state | Billing state or province |
| billing_address > country | Billing country name |
| billing_address > country_code | Billing country code |
| billing_address > phone | Billing phone number |
| billing_address > email | Billing email address |
| billing_address > street | Billing street address |
| billing_address > street_2 | Additional billing street information (can be blank*) |
| billing_address > tax_office | Tax office name (can be blank*) |
| billing_address > tax_id | Tax identification number (can be blank*) |
| billing_address > company | Company name for billing (can be blank*) |
| billing_address > firstname | Billing contact first name |
| billing_address > lastname | Billing contact last name |
Rooms
| Name | Description |
|---|---|
| rooms > id | Room reservation ID |
| rooms > state | The line item state in reservation (reserved,confirmed,canceled)* |
| rooms > code | Inventory code |
| rooms > number | Assigned room number (can be blank*) |
| rooms > voucher_number | Reservation voucher number |
| rooms > availability_group | Inventory availability group code |
| rooms > rate_code | Rate Code |
| rooms > rate_plan_code | Rate plan code identifier |
| rooms > inv_code | Inventory Code (Allocation group) |
| rooms > non_refundable | Indicates whether the rate is non-refundable |
| rooms > price | Total price without tax (BeforeTax) |
| rooms > total | Total price (AfterTax) |
| rooms > nights | Number of nights |
| rooms > meal_plan | Meal plan code |
| rooms > meal_plan_presentation | Meal plan display name |
| rooms > total_guest | Total guest count in the room |
| rooms > total_adult | Adult guest count |
| rooms > child_ages | Child ages list |
| rooms > name | Room type name |
| rooms > name_presentation | Room type display name |
| rooms > checkin_date | Room check-in date |
| rooms > checkout_date | Room check-out date |
| rooms > extra_info | Extra information for room (can be blank*) |
| rooms > daily_prices | See daily_prices json structure |
| rooms > extras | See extras json structure |
| rooms > updated_at | Last update timestamp for the room line |
| rooms > meta | Additional metadata |
| rooms > extras_total | Extras total amount for the room |
| rooms > fixed_adjustments_total | Fixed adjustments total |
| rooms > included_taxes_total | Included taxes total |
| rooms > excluded_fees_and_taxes_total | Excluded taxes and fees total |
| rooms > cancelation_refund_total | Refund total for cancellation |
| rooms > cancelation_refund_tax_type | Refund tax calculation type |
| rooms > cancelation_penalty_total | Cancellation penalty total |
| rooms > cancelation_penalty_tax_type | Penalty tax calculation type |
| rooms > promotions_total | Promotions total applied to the room |
| rooms > room_base_price | Room base price before extras |
| rooms > room_sub_total | Room subtotal including extras before tax |
| rooms > comments | See comments json structure |
Daily Prices
| Name | Description |
|---|---|
| rooms > daily_prices > date | Date of the nightly rate |
| rooms > daily_prices > price | Final nightly price applied for the room |
| rooms > daily_prices > original_price | Original nightly price before discounts |
| rooms > daily_prices > discount | Discount amount applied to the nightly rate |
| rooms > daily_prices > rate_code | Rate code applied for the nightly price |
| rooms > daily_prices > version | Pricing calculation version |
Extras
| Name | Description |
|---|---|
| rooms > extras > name | Extra service or tax name |
| rooms > extras > price | Price of the extra item |
| rooms > extras > base_price | Base price of the extra item before promotions |
| rooms > extras > code | Extra service code (can be blank*) |
| rooms > extras > promotions_total | Total promotion discount applied to the extra |
| rooms > extras > is_extra | Indicates whether the item is an extra service or a tax |
| rooms > extras > total | Total amount of the extra item |
| rooms > extras > quantity | Quantity of the extra item |
| rooms > extras > dates | Dates that the extra applies to (can be empty) |
| rooms > extras > repeat_type | Extra service repetition type (first_night, per_night, etc.) |
| rooms > extras > included_in_price | Indicates whether the tax is included in the room price |
Comments
| Name | Description |
|---|---|
| rooms > comments > body | Comment content |
| rooms > comments > channel_note | Indicates whether the comment is coming from the channel |
| rooms > comments > housekeeping | Housekeeping related comment flag (can be null) |
| rooms > comments > guest_visible | Indicates whether the comment is visible to the guest |
Payments
| Name | Description |
|---|---|
| payments > id | Unique payment record ID |
| payments > state | Payment state (e.g., checkout, completed, pending, refunded) |
| payments > amount | Payment amount |
| payments > currency | Payment currency (ISO-4217) |
| payments > exchanged_amount | Exchanged payment amount in property currency (can be blank*) |
| payments > exchange_currency | Property currency code (can be blank*) |
| payments > exchange_rate | Exchange rate applied (can be blank*) |
| payments > paid_at | Payment timestamp (ISO-8601) |
| payments > payment_method | Payment method code (credit_card, bank_transfer, cash, paypal) |
| payments > payment_method_name | Payment method display name |
| payments > installment | Number of installments (can be blank*) |
| payments > response_code | Payment gateway response code (can be blank*) |
blank: Empty or Null
payment: We don't share credit card information.
reserved: Initial state of reservation.
confirmed: Next state of reservation when Hotelier confirms it.
canceled: Reservation has been canceled by the guest or channel.