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.