Read-only lookup endpoints backing property setup and integration mapping - property kinds, room kinds, room amenities, property services and facilities, sellable currencies, ISO country codes, and the master list of connectable OTA channel codes.
openapi: 3.0.3
info:
title: HotelRunner Custom Apps REST API
description: >-
The HotelRunner Custom Apps REST API lets a property's PMS or revenue
management system connect to HotelRunner - retrieve room/rate
configuration, push availability and rate updates, retrieve and
acknowledge reservations, fire reservation state-change events, list
connected sales channels, and read setup reference data. All Custom Apps
endpoints require `token` and `hr_id` query-string credentials issued from
the property's HotelRunner Partners extranet ("My Property" section, or a
sandbox test property for PMS partners). HotelRunner can also push new and
updated reservations to a partner-hosted HTTPS URL as a webhook (see the
Realtime Push documentation) - this is not modeled as an OpenAPI path
because HotelRunner is the caller, not the server, for that flow.
Endpoints and fields below are transcribed from HotelRunner's public
developer docs at developers.hotelrunner.com; fields not explicitly shown
in an example response are marked as modeled/inferred in comments where
relevant.
version: v2
contact:
name: HotelRunner
url: https://developers.hotelrunner.com/
servers:
- url: https://app.hotelrunner.com/api/v2/apps
description: Custom Apps REST API (production)
- url: https://app.hotelrunner.com
description: Public reference/services data endpoints
security:
- tokenAuth: []
tags:
- name: Inventory
description: Room types, master rates, availability, and restrictions.
- name: Reservations
description: Retrieve, confirm, cancel, and acknowledge reservations.
- name: Channels
description: Connected OTA / sales channel status.
- name: Reference Data
description: Read-only lookup data used for property and integration setup.
paths:
/rooms:
get:
operationId: listRooms
tags:
- Inventory
summary: Get room list
description: >-
Returns all rooms/room types and their master rate configuration for
the property identified by hr_id, including which channels each room
is connected to and whether availability, restrictions, and price
updates are enabled for it.
parameters:
- $ref: '#/components/parameters/Token'
- $ref: '#/components/parameters/HrId'
responses:
'200':
description: A list of rooms.
content:
application/json:
schema:
type: object
properties:
rooms:
type: array
items:
$ref: '#/components/schemas/Room'
'401':
$ref: '#/components/responses/Unauthorized'
/rooms/~:
put:
operationId: updateRoomDateRange
tags:
- Inventory
summary: Update room availability/rates/restrictions over a date range
description: >-
Updates availability, price, stop-sale, min/max stay, and CTA/CTD
restrictions for a single room type's master rate across a start/end
date range, optionally scoped to specific weekdays and channel codes.
Parameters are passed as query-string values, not a JSON body.
parameters:
- $ref: '#/components/parameters/Token'
- $ref: '#/components/parameters/HrId'
- name: room_code
in: query
required: true
description: The room code to update.
schema:
type: string
- name: '@rooms.inv_code'
in: query
required: true
description: >-
Inventory code to update. Only updates the room type and its
master rate.
schema:
type: string
- name: '@rooms.rate_code'
in: query
required: false
description: Rate code to update when price_update is enabled for the room.
schema:
type: string
- name: start_date
in: query
required: true
schema:
type: string
format: date
- name: end_date
in: query
required: true
schema:
type: string
format: date
- name: availability
in: query
required: false
schema:
type: integer
- name: price
in: query
required: false
schema:
type: number
- name: stop_sale
in: query
required: false
schema:
type: integer
enum: [0, 1]
- name: cta
in: query
required: false
description: Closed to arrival.
schema:
type: integer
enum: [0, 1]
- name: ctd
in: query
required: false
description: Closed to departure.
schema:
type: integer
enum: [0, 1]
- name: min_stay
in: query
required: false
schema:
type: integer
- name: max_stay
in: query
required: false
schema:
type: integer
- name: days
in: query
required: false
description: 'Weekday filter, Sunday=0 through Saturday=6.'
schema:
type: array
items:
type: integer
minimum: 0
maximum: 6
- name: channel_codes
in: query
required: false
description: Restrict the update to specific channel codes.
schema:
type: array
items:
type: string
responses:
'200':
description: Update accepted or queued for retry.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateResult'
'401':
$ref: '#/components/responses/Unauthorized'
/rooms/daily:
put:
operationId: updateRoomsMultiDates
tags:
- Inventory
summary: Bulk update rooms across multiple dates
description: >-
Updates availability, price, and restrictions for one or more rooms
across up to 90 explicit dates per call, optionally scoped to
specific channel codes per room.
parameters:
- $ref: '#/components/parameters/Token'
- $ref: '#/components/parameters/HrId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
rooms:
type: array
items:
type: object
required:
- inv_code
- dates
properties:
inv_code:
type: string
channel_codes:
type: array
items:
type: string
dates:
type: array
maxItems: 90
items:
type: object
required:
- date
properties:
date:
type: string
format: date
availability:
type: string
price:
type: string
min_stay:
type: integer
max_stay:
type: integer
stop_sale:
type: integer
enum: [0, 1]
cta:
type: integer
enum: [0, 1]
ctd:
type: integer
enum: [0, 1]
responses:
'200':
description: Update accepted, queued for retry, or partially failed.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/UpdateResult'
- type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
'401':
$ref: '#/components/responses/Unauthorized'
/reservations:
get:
operationId: listReservations
tags:
- Reservations
summary: Retrieve reservations
description: >-
Lists reservations for the property, defaulting to undelivered
reservations from the last 10 days. Supports pagination and filters
for a specific reservation number, modified reservations, and booked
(created) reservations.
parameters:
- $ref: '#/components/parameters/Token'
- $ref: '#/components/parameters/HrId'
- name: from_date
in: query
description: 'Format YYYY-MM-DD. Defaults to 10 days before today.'
schema:
type: string
format: date
- name: from_last_update_date
in: query
schema:
type: string
format: date
- name: per_page
in: query
schema:
type: integer
default: 10
- name: page
in: query
schema:
type: integer
default: 1
- name: reservation_number
in: query
schema:
type: string
- name: undelivered
in: query
schema:
type: boolean
default: true
- name: modified
in: query
schema:
type: boolean
default: false
- name: booked
in: query
schema:
type: boolean
default: false
responses:
'200':
description: A page of reservations.
content:
application/json:
schema:
type: object
properties:
reservations:
type: array
items:
$ref: '#/components/schemas/Reservation'
count:
type: integer
current_page:
type: integer
pages:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
/reservations/fire:
put:
operationId: updateReservationState
tags:
- Reservations
summary: Confirm or cancel a reservation
description: >-
Fires a state-change event on a reservation identified by its
HotelRunner reservation number (hr_number). Use event=confirm to
confirm and event=cancel to cancel, supplying a cancel_reason when
cancelling.
parameters:
- $ref: '#/components/parameters/Token'
- $ref: '#/components/parameters/HrId'
- name: hr_number
in: query
required: true
description: The reservation code in HotelRunner.
schema:
type: string
- name: event
in: query
required: true
schema:
type: string
enum: [confirm, cancel]
- name: cancel_reason
in: query
required: false
description: Required when event=cancel.
schema:
type: string
enum: [customer, no_room, no_show, invalid_price]
responses:
'200':
description: State change result.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResult'
'401':
$ref: '#/components/responses/Unauthorized'
/reservations/~:
put:
operationId: confirmReservationDelivery
tags:
- Reservations
summary: Confirm reservation delivery
description: >-
Acknowledges that a reservation delivered via the retrieve/realtime
push flow was received and processed by the PMS, identified by the
message_uid found at the end of the reservation's JSON payload.
parameters:
- $ref: '#/components/parameters/Token'
- $ref: '#/components/parameters/HrId'
- name: message_uid
in: query
required: true
description: Unique ID of the reservation delivery message.
schema:
type: string
- name: pms_number
in: query
required: false
description: The reservation number in the connecting PMS.
schema:
type: string
responses:
'200':
description: Acknowledgement result.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResult'
'401':
$ref: '#/components/responses/Unauthorized'
/infos/connected_channels:
get:
operationId: listConnectedChannels
tags:
- Channels
summary: List connected channels
description: >-
Returns all OTA / sales channels connected to the property along with
counts of in-progress, succeeded, and failed distribution updates for
each channel.
parameters:
- $ref: '#/components/parameters/Token'
- $ref: '#/components/parameters/HrId'
responses:
'200':
description: Connected channel list.
content:
application/json:
schema:
type: object
properties:
channels:
type: array
items:
$ref: '#/components/schemas/Channel'
'401':
$ref: '#/components/responses/Unauthorized'
/api/property/types.json:
get:
operationId: getPropertyKinds
tags:
- Reference Data
summary: Get property kinds
description: Returns the id-name mapping of property kinds (Villa, Resort, etc).
responses:
'200':
description: Property kind list.
content:
application/json:
schema:
$ref: '#/components/schemas/IdNameList'
/api/room/types.json:
get:
operationId: getRoomKinds
tags:
- Reference Data
summary: Get room kinds
description: Returns the id-name mapping of room kinds (Apartment, Bungalow, etc).
responses:
'200':
description: Room kind list.
content:
application/json:
schema:
$ref: '#/components/schemas/IdNameList'
/api/currency/currencies.json:
get:
operationId: getCurrencies
tags:
- Reference Data
summary: Get currencies
description: Returns the selectable currency list for a property.
responses:
'200':
description: Currency list.
content:
application/json:
schema:
$ref: '#/components/schemas/IdNameList'
/services/get-property-services:
get:
operationId: getPropertyServices
tags:
- Reference Data
summary: Get property services
description: >-
Returns the id-name mapping of general property services shown on a
property's listing. Path documented under HotelRunner's Services
navigation; exact JSON response is modeled on the sibling reference
endpoints.
responses:
'200':
description: Property service list.
content:
application/json:
schema:
$ref: '#/components/schemas/IdNameList'
/services/get-property-facilities:
get:
operationId: getPropertyFacilities
tags:
- Reference Data
summary: Get property facilities
description: >-
Returns the id-name mapping of property facilities. Path documented
under HotelRunner's Services navigation; exact JSON response is
modeled on the sibling reference endpoints.
responses:
'200':
description: Property facility list.
content:
application/json:
schema:
$ref: '#/components/schemas/IdNameList'
/services/get-room-amenities:
get:
operationId: getRoomAmenities
tags:
- Reference Data
summary: Get room amenities
description: >-
Returns the id-name mapping of room amenities. Path documented under
HotelRunner's Services navigation; exact JSON response is modeled on
the sibling reference endpoints.
responses:
'200':
description: Room amenity list.
content:
application/json:
schema:
$ref: '#/components/schemas/IdNameList'
/services/country-codes:
get:
operationId: getCountryCodes
tags:
- Reference Data
summary: Get country codes
description: Returns the ISO country code list used across property and guest setup.
responses:
'200':
description: Country code list.
content:
application/json:
schema:
type: object
additionalProperties:
type: string
/services/channel-list:
get:
operationId: getChannelList
tags:
- Reference Data
summary: Get channel list
description: >-
Returns the master list of OTA / sales channel codes HotelRunner can
connect a property to, independent of which channels a given property
currently has enabled.
responses:
'200':
description: Channel code list.
content:
application/json:
schema:
$ref: '#/components/schemas/IdNameList'
components:
securitySchemes:
tokenAuth:
type: apiKey
in: query
name: token
description: >-
API token issued in the property's HotelRunner Partners extranet
("My Property" section) or PMS sandbox account. Always sent together
with the hr_id query parameter identifying the property.
parameters:
Token:
name: token
in: query
required: true
description: Authentication token for the property.
schema:
type: string
HrId:
name: hr_id
in: query
required: true
description: HotelRunner property identifier.
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid token/hr_id.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResult'
schemas:
Room:
type: object
properties:
rate_code:
type: string
inv_code:
type: string
availability_update:
type: boolean
restrictions_update:
type: boolean
price_update:
type: boolean
pricing_type:
type: string
example: guest_based
name:
type: string
description:
type: string
policy:
type: string
room_capacity:
type: integer
adult_capacity:
type: integer
is_master:
type: boolean
shared:
type: boolean
channel_codes:
type: array
items:
type: string
sales_currency:
type: string
sell_online:
type: boolean
UpdateResult:
type: object
properties:
status:
type: string
enum: [ok, try_again]
transaction_id:
type: string
StatusResult:
type: object
properties:
status:
type: string
enum: [ok, error]
message:
type: string
Reservation:
type: object
properties:
reservation_id:
type: integer
hr_number:
type: string
channel:
type: string
state:
type: string
example: reserved
guest:
type: string
total:
type: number
currency:
type: string
checkin_date:
type: string
format: date
checkout_date:
type: string
format: date
message_uid:
type: string
description: >-
Unique ID of the delivery message, used with confirmReservationDelivery.
Documented as appearing at the end of the reservation JSON; not shown
in HotelRunner's abbreviated example response (modeled).
x-endpointsModeled:
- message_uid field position/shape
Channel:
type: object
properties:
name:
type: string
code:
type: string
in_progress:
type: integer
succeeded:
type: integer
failed:
type: integer
IdNameList:
type: object
additionalProperties:
type: string
description: >-
Modeled as an id-to-name map per HotelRunner's own description of
these endpoints ("id-name mapping"); HotelRunner's docs did not show
a literal example payload for this endpoint.