---
title: "Query Reservations"
method: GET
path: "/reservations"
tags: ["Reservations"]
---

# Query Reservations

`GET /reservations`

You can query reservations by making a request to this endpoint.

## Query parameters

- `reservation_code` string
- `channel_id` string
- `property_id` integer
- `status` 'wait_accept' | 'wait_pay' | 'accepted' | 'cancelled' | 'denied' | 'timeout'
- `start_check_in_date` string, date
- `end_check_in_date` string, date
- `start_check_out_date` string, date
- `end_check_out_date` string, date
- `order_by` 'booked_at' | 'check_in_date' | 'check_out_date' | 'cancelled_at' | 'created_at'
- `channel_type` 'airbnb' | 'booking.com' | 'agoda' | 'expedia' | 'vrbo' | 'trip.com' | 'booking_site' | 'tujia_intl' | 'hostex_direct' | 'tujia' | 'xiaozhu' | 'meituan_bnb' | 'meituan_hotel' | 'muniao' | 'fliggy' | 'zhukeyun' | 'tiktok' | 'xiaohongshu' | 'ctrip' | 'houfy' — The type of the channel. See [Supported Channels](/reference/supported-channels) for more information.
- `offset` integer
- `limit` integer

## Response `200`

- object
  - `request_id` string, required — Unique identifier for the request.
  - `error_code` integer, required — Numeric error code representing the status of the response. A value of `200` indicates success. <br> See the [Error Codes](/reference/error-manual#error-codes) section for more information.
  - `error_msg` string, required — Message detailing the status of the response.
  - `data` object, required
    - `reservations` object[], required — List of the properties
      - `reservation_code` string, required — The reservation code. Multiple stays are allowed for the same reservation. In the case of multiple stays, all stays will share the same reservation code. For example: `0-1234567-abcdef`
      - `stay_code` string, required — The stay code of the reservation. For example: `0-1234567-abcdef` or `0-1234567_1-abcdef`(if there are multiple stays for the same reservation)
      - `channel_id` string, required — The reservation ID in the channel.
      - `property_id` integer, required — The property ID. If an reservation fails to be allocated to a property, `0` will be returned.
      - `channel_type` 'airbnb' | 'booking.com' | 'agoda' | 'expedia' | 'vrbo' | 'trip.com' | 'booking_site' | 'tujia_intl' | 'hostex_direct' | 'tujia' | 'xiaozhu' | 'meituan_bnb' | 'meituan_hotel' | 'muniao' | 'fliggy' | 'zhukeyun' | 'tiktok' | 'xiaohongshu' | 'ctrip' | 'houfy', required — The type of the channel. See [Supported Channels](/reference/supported-channels) for more information.
      - `listing_id` string, required — The unique identifier for different channels. <br>For example, the listing id for Airbnb is the Airbnb listing id, and the listing id for Booking.com is the Booking.com room id - rateplan id.
      - `check_in_date` string, date, required — The check-in date of the reservation in YYYY-MM-DD format. Example: `2019-01-01`
      - `check_out_date` string, date, required — The check-out date of the reservation in YYYY-MM-DD format. Example: `2019-01-01`
      - `number_of_guests` integer, required — The total number of guests for the reservation
      - `number_of_adults` integer — The number of adults for the reservation
      - `number_of_children` integer — The number of children for the reservation
      - `number_of_infants` integer — The number of infants for the reservation
      - `number_of_pets` integer — The number of pets for the reservation
      - `status` 'wait_accept' | 'wait_pay' | 'accepted' | 'cancelled' | 'denied' | 'timeout', required
      - `guest_name` string, nullable — The default name of the guest. If it has been modified, it may differ from the name in the `guests`.
      - `guest_phone` string, nullable — The default phone of the guest. If it has been modified, it may differ from the name in the `guests`.
      - `guest_email` string, nullable — The default email of the guest. If it has been modified, it may differ from the name in the `guests`.
      - `cancelled_at` string, date-time, nullable — The datetime when the reservation was cancelled, `null` will be returned if the reservation is not cancelled in ISO 8601 format. Example: `2019-01-01T00:00:00+00:00`
      - `booked_at` string, date-time, required — The datetime when the reservation was booked in ISO 8601 format. Example: `2019-01-01T00:00:00+00:00`
      - `created_at` string, date-time, required — The datetime when the reservation was created in Hostex in ISO 8601 format. Example: `2019-01-01T00:00:00+00:00`
      - `creator` string — The creator name of the reservation
      - `rates` object
        - `total_rate` object — The order rate includes commission.
          - `currency` string — The currency code for the reservation amounts. See [Supported Currencies](/reference/supported-currencies) for more information.
          - `amount` number
        - `total_commission` object — The total commission of the order.
          - `currency` string — The currency code for the reservation amounts. See [Supported Currencies](/reference/supported-currencies) for more information.
          - `amount` number
        - `rate` object — The reservation rate includes commission.
          - `currency` string — The currency code for the reservation amounts. See [Supported Currencies](/reference/supported-currencies) for more information.
          - `amount` number
        - `commission` object — The commission of the reservation (if it is a multi-reservation order, the amount is allocated from the order commission).
          - `currency` string — The currency code for the reservation amounts. See [Supported Currencies](/reference/supported-currencies) for more information.
          - `amount` number
        - `tax` object, nullable — The taxes of the reservation. `null` will be returned if the reservation has no taxes.
          - `currency` string — The currency code for the reservation amounts. See [Supported Currencies](/reference/supported-currencies) for more information.
          - `amount` number
        - `details` object[] — The rate details of the reservation
          - `type` string — The type of the rate detail
          - `description` string — The description of the rate detail
          - `currency` string — The currency code for the reservation amounts. See [Supported Currencies](/reference/supported-currencies) for more information.
          - `amount` number
      - `payment` object — The payment collection status of the reservation, computed the same way as the Received / Unreceived status shown in the Hostex web app. Settlement is calculated at the order level, so all stays sharing the same `reservation_code` carry identical `payment` values — do not sum them across stays. Most meaningful for Hostex Direct (manually created) reservations where income is recorded against the order via `POST /transactions`; channel-collected reservations may report `unreceived` if no income has been recorded in Hostex.
        - `currency` string — The currency code for the payment amounts. See [Supported Currencies](/reference/supported-currencies) for more information.
        - `total_amount` number — The amount expected to be received for the order (the settlement basis used for the Received / Unreceived status).
        - `received_amount` number — The amount already received, i.e. the sum of recorded house-fee income for the order.
        - `balance_amount` number — The amount still outstanding (`total_amount - received_amount`, never negative). `0` when fully or over collected.
        - `status` 'unreceived' | 'partial' | 'received' | 'over_received' — The collection status: `unreceived` (nothing received), `partial` (received less than expected), `received` (fully settled), `over_received` (received more than expected).
      - `check_in_details` object — The check-in details of the reservation
        - `arrival_at` object, nullable — The arrival time of the reservation. If not specified, `null` will be returned.
          - `hour` integer
          - `minute` integer
        - `departure_at` object, nullable — The departure time of the reservation. If not specified, `null` will be returned.
          - `hour` integer
          - `minute` integer
        - `lock_code` string, nullable — The lock code of the reservation. If not specified, `null` will be returned.
        - `lock_code_visible_after` string — The lock code will be visible after this time, formatted as `HH:mm`.
        - `deposit` number — The deposit amount in the host's currency. For example, if the currency is USD, 100 means 100 US Dollars.
        - `id_required` 'not_required' | 'required' | 'required_with_review' — Whether the guest must register / upload identity documents (ID) for this stay before check-in. Defaults to `not_required` when no setting has been applied.
        - `check_in_guide_url` string — The check-in guide URL.
      - `remarks` string — Remarks from the [Hostex Host Portal](https://hostex.io/app/reservations)
      - `channel_remarks` string — Remarks from the channel
      - `conversation_id` string — The conversation ID of the reservation. If not specified, `null` will be returned.
      - `tags` string[] — Tags from the [Hostex Host Portal](https://hostex.io/app/reservations)
      - `custom_channel` object — Custom channels created from the [Custom Options Page](https://hostex.io/app/settings/custom-options). See [Query Custom Channel](/reference/query-custom-channels) for retrieving custom channels.
        - `id` integer, required
        - `name` string, required
      - `guests` object[] — In some special cases (e.g., the host manually deleted the guest information), the guests field may return an empty array, so you need to handle the empty case.
        - `id` integer
        - `name` string, nullable
        - `phone` string, nullable
        - `email` string, nullable
        - `id_type` 'passport' | 'id_card' | 'others', nullable
        - `id_number` string, nullable
        - `gender` 'male' | 'female', nullable
        - `country` string, nullable — ISO 3166-1 Alpha-2
        - `is_booker` boolean — Used to determine whether it is the booker of the reservation.
        - `id_images` object[] — ID document images uploaded for this guest. Returns an empty array when no image has been uploaded.
          - `id` integer — Internal ID of the image record.
          - `url` string, nullable — Extra-large variant URL of the uploaded image, served by the image CDN.
      - `custom_fields` object, nullable — Custom fields.
      - `in_reservation_box` boolean — Whether the reservation is in the reservation box.
      - `additional_fees` object[] — Additional fees parsed from `channel_remarks` (e.g., city tax, tourist tax). Currently only available for some channels (e.g., Booking.com) that include an `Additional Fee:` line in the channel remark. Returns an empty array when no additional fees can be parsed.
        - `name` string — The name of the additional fee item, as provided by the channel (may be in the channel's locale, e.g., `imposto municipal`).
        - `currency` string — The currency code of the additional fee, inherited from the reservation rate. See [Supported Currencies](/reference/supported-currencies) for more information.
        - `amount` number — The amount of the additional fee in the specified currency.
      - `checkin_guide_images` object[] — ID document images uploaded by guests through the online check-in guide for this reservation. Includes all images submitted on the reservation, even those not yet linked to a guest record (in which case `client_id` is `null`). Returns an empty array when no images have been uploaded.
        - `id` integer — Internal ID of the image record.
        - `client_id` integer, nullable — ID of the guest this image is linked to. `null` if the image has not been associated with a guest yet.
        - `url` string, nullable — Extra-large variant URL of the uploaded image, served by the image CDN.

---

[API](https://skmtc.net/hostex/apis/hostex-api.md) · [All operations](https://skmtc.net/hostex/apis/hostex-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hostex/hostex-api/versions/a3fa555dee66/schema)