NAV
curl
For Properties

Introduction [Property]

Welcome to the HotelRunner Apps API! You can use our Apps API to access HotelRunner’s api endpoints, which can get information on rooms, reservations, make price & availability updates and even receive real-time reservation updates.

You can view code examples in the dark area to the right.

Authentication [Property]

HotelRunner uses TOKEN and HR_ID keys to allow access to the API. You can register a new HotelRunner Apps API key at your property panel under My Property section.

Channels [Property]

Get HotelRunner Channel List

curl "https://app.hotelrunner.com/api/v2/apps/infos/channels?token={TOKEN}&hr_id={HR_ID}"

The above command returns JSON structured like this:

{
    "channels": [
        {
            "name": "Booking.com",
            "code": "bookingcom"
        },
        {
            "name": "HRS",
            "code": "hrs"
        },
        {
            "name": "Expedia Inc.",
            "code": "expedia"
        }
    ]
}

This endpoint retrieves all available channels of HotelRunner.

HTTP Request

GET https://app.hotelrunner.com/api/v1/apps/infos/channels

Channel Object

Name Description
name Channel name
code Channel code. (This code will be used on Room calendar updates.)

Get Connected Channel List of a Property

curl "https://app.hotelrunner.com/api/v2/apps/infos/connected_channels?token={TOKEN}&hr_id={HR_ID}"

The above command returns JSON structured like this:

{
    "channels": [
        {
            "name": "Online",
            "code": "online",
            "in_progress": 0,
            "succeeded": 0,
            "failed": 0
        },
        {
            "name": "Booking.com",
            "code": "bookingcom",
            "in_progress": 132,
            "succeeded": 297,
            "failed": 0
        }
    ]
}

This endpoint retrieves all connected channels of a Property with process stats.

HTTP Request

GET https://app.hotelrunner.com/api/v2/apps/infos/connected_channels

Property Channel Object

Name Description
name Channel name
code Channel code. (This code will be used on Room calendar updates.)
in_progress Total process count that are being processed.
succeeded Total process count that were successfully updated.
failed Total process count that were failed.

Rooms [Property]

Get Room List

curl "https://app.hotelrunner.com/api/v2/apps/rooms?token={TOKEN}&hr_id={HR_ID}"

The above command returns JSON structured like this:

{
    "rooms": [
        {
            "code": "HR:1",
            "availability_group": "HR:1",
            "availability_update": true,
            "restrictions_update": true,
            "price_update": true,
            "name": "Standard Room",
            "description": "Standard Room Description",
            "policy": "Standard Room Policy",
            "room_capacity": 3,
            "adult_capacity": 2,
            "channel_codes": [
                "bookingcom",
                "online",
                "hrs",
                "expedia"
            ]
        },
        {
            "code": "NR:HR:1",
            "availability_group": "HR:1",
            "availability_update": false,
            "restrictions_update": false,
            "price_update": false,
            "name": "Standard Room - NR",
            "description": "Standard Room Description",
            "policy": "Standard Room Policy",
            "room_capacity": 3,
            "adult_capacity": 2,
            "channel_codes": [
                "bookingcom",
                "online",
                "hrs",
                "expedia"
            ]
        },
        {
            "code": "HR:2",
            "availability_group": "HR:2",
            "availability_update": true,
            "restrictions_update": true,
            "price_update": true,
            "name": "Double Room",
            "description": "Double Room Description",
            "policy": "Double Room Policy",
            "room_capacity": 2,
            "adult_capacity": 2,
            "channel_codes": [
                "bookingcom",
                "online",
                "hrs"
            ]
        }
    ]
}

This endpoint retrieves all rooms of property.

HTTP Request

GET https://app.hotelrunner.com/api/v2/apps/rooms

Room Object

Name Description
code Room code on HotelRunner (NR means Non refundable)
availability_group Room availability group on HotelRunner. All availabilities of rates are same within same group.
availability_update Only room whose availability_update=true` can update availabilities.
restrictions_update Only room whose restrictions_update=true` can update restrictions.
price_update Only room whose price_update=true` can update prices.
name Name of room
description Description of room
policy Free text policy for room
room_capacity Maximum room capacity including children
adult_capacity Maximum adult count that can stay in room
channel_codes Channel codes of which room is connected with

Update Room

curl -X PUT --data "hr_id={HR_ID}&token={TOKEN}&room_code={ROOM_CODE}&channel_codes[]={CHANNEL_CODE_1}&channel_codes[]={CHANNEL_CODE_2}&start_date={START_DATE}&end_date={END_DATE}&availability={AVAILABILITY}&price={PRICE}&min_stay={MIN_STAY}&stop_sale={STOP_SALE}" https://app.hotelrunner.com/api/v1/apps/rooms/~

The above command returns json structured like this:


    {
        "status": "ok", 
        "transaction_id": "123456789" 
    }



    {
        "status": "try_again", 
        "transaction_id": "123456789" 
    }


This endpoint updates the room.

PUT https://app.hotelrunner.com/api/v2/apps/rooms/~

Query Parameters

Parameter Default Required Description
room_code - Yes Room code that will be updated.
availability - No Don’t send this parameter if you don’t want to update availability.
price - No Don’t send this parameter if you don’t want to update price.
stop_sale - No Don’t send this parameter if you don’t want to update stop sale. Accepted values: 1 or 0
cta - No Don’t send this parameter if you don’t want to update CTA. Accepted values: 1 or 0
ctd - No Don’t send this parameter if you don’t want to update CTD. Accepted values: 1 or 0
min_stay - No Don’t send this parameter if you don’t want to update min_stay.
start_date - Yes Format: YYYY-MM-DD Start date
end_date - Yes Format: YYYY-MM-DD End date
days [0,1,2,3,4,5,6] No Type: Array Used to update specific week days within given date range. (Sunday: 0)
channel_codes All connected channels of room No Type: Array Used to update specific channels. (eg. [‘bookingcom’, 'online’])

Get Transaction Details

curl "https://app.hotelrunner.com/api/v2/apps/infos/transaction_details?transaction_id={TRANSACTION_ID}&token={TOKEN}&hr_id={HR_ID}"

The above command returns json structured like this:

{
  "transaction": {
    "id": "883770514",
    "counts": {
      "failed": 1,
      "succeeded": 1,
      "in_progress": 0
    },
    "details": [
      {
        "id": 12529,
        "channel_code": "bookingcom",
        "state": "failed",
        "name": "Люкс (68366) - Стандартный тариф - 1 Person",
        "code": "156754:8833301",
        "allocation_group": "8833301",
        "created_at": "2015-10-16T08:01:29Z",
        "pid": 9651,
        "error_message": null
      },
      {
        "id": null,
        "channel_code": "online",
        "state": "succeeded",
        "name": "Online",
        "code": "Online",
        "allocation_group": "Online",
        "created_at": "2015-10-16T07:54:25Z",
        "pid": null,
        "error_message": null
      }
    ]
  }
}

This endpoint returns update status logs of given transaction id

GET https://app.hotelrunner.com/api/v1/apps/infos/transaction_details

Query Parameters

Parameter Default Required Description
transaction_id - Yes Each room update request returns transaction_id.

Reservations [Property]

Get All Reservations

curl "https://app.hotelrunner.com/api/v2/apps/reservations?token={TOKEN}&hr_id={HR_ID}"

The above command returns JSON structured like this:

{
  "reservations": [
    {
          "hr_number": "R754208185",
          "provider_number": null,
          "channel": null,
          "state": "confirmed",
          "modified": false,
          "guest": "John Doe",
          "cancel_reason": null,
          "completed_at": "2015-01-21T10:01:25Z",
          "updated_at": "2015-01-21T09:02:51Z",
          "sub_total": 185.0,
          "extras_total": 45.0,
          "adjustments_total": 0.0,
          "tax_total": 15.0,
          "total": 245.0,
          "currency": "EUR",
          "checkin_date": "2015-01-11",
          "checkout_date": "2015-01-12",
          "note": null,
          "payment": "credit_card",
          "paid_amount": 0.0,
          "address": {
            "city": "istanbul",
            "state": "",
            "country": "Turkey",
            "phone": "90955223454",
            "email": "guest@example.net",
            "street": "Bagdat Cad. Istanbul",
            "street_2": null
          },
          "rooms": [
            {
              "state": "reserved",
              "code": "HR:10105",
              "availability_group": "HR:10105",
              "price": 200.0,
              "non_refundable": false,
              "nights": 1,
              "total_guest": 2,
              "total_adult": 2,
              "child_ages": [

              ],
              "name": "Queen Room - Disability Access - Deluxe Rate",
              "checkin_date": "2015-01-11",
              "checkout_date": "2015-01-12",
              "extra_info": "Room Extra Info:Modern bir şekilde dekore edilmiş bu stüdyoda çalışma masası ve özel banyo bulunmaktadır.\nMeal Plan:Kahvaltı oda fiyatına dahildir.\nNon-Smoking Room",
              "daily_prices": [
                {
                  "date": "2015-01-11",
                  "price": "200.0"
                }
              ],
              "extras": [
                {
                  "name": "Airport Transfer (1 Person)",
                  "price": "45.0"
                }
              ]
            }
          ]
        }
  ],
  "count": 1,
  "current_page": 1,
  "pages": 1
}

This endpoint retrieves all reservations with pagination.

HTTP Request

GET https://app.hotelrunner.com/api/v2/apps/reservations

Query Parameters

Parameter Default Required Description
from_date 10 days before No Format: YYYY-MM-DD. If provided, reservations after this date will be retrieved.
per_page 10 No Number of reservations per page.
page 1 No Number of current page.
reservation_number - No Used to get a specific reservation. It can be either HotelRunner or Channel reservation code.
undelivered true No If set to false, all reservations will be shown with pagination

Reservation Object

Name Description
hr_number Reservation code on HotelRunner
provider_number Reservation code on Sales Channel (can be blank*)
channel Sales channel code (can be blank*)
state Reservation status on HotelRunner (reserved,confirmed, canceled)*
modified Flag that shows whether the reservation has been modified after your latest activity or not.
guest Guest name, who made the reservation
cancel_reason Cancel reason (can be blank*)
completed_at The time that shows when HotelRunner received the reservation (UTC)
updated_at The time that shows when HotelRunner received the latest update (UTC)
sub_total Sub total (tax not included)
extras_total Extras total (tax not included)
adjustments_total Adjustments total (Price adjustments total that made by Property Admin)
tax_total Tax total
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)
paid_amount Payment total
address See address json structure.
rooms > code The room code.
rooms > state The line item state in reservation. (reserved,confirmed, canceled)*

*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.

Real-time [Property]

Real-time Push Reservation

The POST you will see coming will look like this:

"https://yourdomain.com/callback?token={TOKEN}&hr_id={HR_ID}&data={JSON_RESERVATION_DATA}"

The above url includes JSON data structured like this:

{
      "reason": "modify",
      "hr_number": "R754208185",
      "provider_number": "32423234422",
      "channel": "Booking.com",
      "state": "confirmed",
      "modified": true,
      "guest": "John Doe",
      "cancel_reason": null,
      "completed_at": "2015-01-21T10:01:25Z",
      "updated_at": "2015-01-21T09:02:51Z",
      "sub_total": 370.0,
      "extras_total": 0.0,
      "adjustments_total": 0.0,
      "tax_total": 30.0,
      "total": 400.0,
      "currency": "EUR",
      "checkin_date": "2015-01-11",
      "checkout_date": "2015-01-12",
      "note": null,
      "payment": "credit_card",
      "paid_amount":0.0,
      "address": {
        "city": "Istanbul",
        "state": "",
        "country": "Turkey",
        "phone": "90955223454",
        "email": "guest@example.net",
        "street": "Bagdat Cad. Istanbul",
        "street_2": null
      },
      "rooms": [
        {
          "state": "reserved",
          "code": "HR:10105",
          "price": 200.0,
          "nights": 1,
          "total_guest": 2,
          "total_adult": 2,
          "child_ages": [

          ],
          "name": "Queen Room - Disability Access - Deluxe Rate",
          "checkin_date": "2015-01-11",
          "checkout_date": "2015-01-12",
          "extra_info": "Room Extra Info:Modern bir şekilde dekore edilmiş bu stüdyoda çalışma masası ve özel banyo bulunmaktadır.\nMeal Plan:Kahvaltı oda fiyatına dahildir.\nNon-Smoking Room",
          "daily_prices": [
            {
              "date": "2015-01-11",
              "price": "200.0"
            }
          ],
          "extras": [

          ]
        },
        {
          "state": "reserved",
          "code": "HR:10105",
          "price": 200.0,
          "nights": 1,
          "total_guest": 2,
          "total_adult": 2,
          "child_ages": [

          ],
          "name": "Single Room - Non Refundable Rate",
          "checkin_date": "2015-01-11",
          "checkout_date": "2015-01-12",
          "extra_info": "Room Extra Info:Modern bir şekilde dekore edilmiş bu stüdyoda çalışma masası ve özel banyo bulunmaktadır.\nMeal Plan:Kahvaltı oda fiyatına dahildir.\nNon-Smoking Room",
          "daily_prices": [
            {
              "date": "2015-01-11",
              "price": "200.0"
            }
          ],
          "extras": [

          ]
        }
      ]
 }


The above command should return json structured like this:


 {
    "status": "ok"
 }

Real-time push reservations provide your application with instant notifications of new/updated reservations as they are received by HotelRunner.

Create a Callback URL

When we have new updates to send your server, we do a simple POST with a payload containing updates to a URL on your server. This callback URL must be HTTPS and support POST method.

https://yourdomain.com/callback

For instance, the POST you will see coming will look like this:

https://yourdomain.com/callback?token={TOKEN}&hr_id={HR_ID}&data={JSON_RESERVATION_DATA}

Reservation Object

Name Description
reason Reason of push notification: (modify, cancel, confirm)
hr_number Reservation code on HotelRunner
provider_number Reservation code on Sales Channel (can be blank*)
channel Sales channel code (can be blank*)
state Reservation status on HotelRunner (reserved,confirmed, canceled)*
modified Flag that shows whether the reservation has been modified after your latest activity or not.
guest Guest name, who made the reservation
cancel_reason Cancel reason (can be blank*)
completed_at The time that shows when HotelRunner received the reservation (UTC)
updated_at The time that shows when HotelRunner received the latest update (UTC)
sub_total Sub total (tax not included)
extras_total Extras total (tax not included)
adjustments_total Adjustments total (Price adjustments total that made by Property Admin)
tax_total Tax total
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)
paid_total Payment total
address See address json structure.
rooms > code The room code.
rooms > state The line item state in reservation. (reserved,confirmed, canceled)*

*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.

Extras

Errors

The HotelRunner Apps API uses the following error codes:

Error Code Meaning
400 Bad Request - Missing required parameter
401 Unauthorized – Your API key is wrong
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable – You requested a format that isn’t json
410 Gone
422 Invalid Resource
429 Too Many Requests
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.