Frequently Asked Questions (FAQ)

Welcome to the FAQ. This section provides answers to common questions about our API's behavior, best practices, and the commercial logic that powers our platform.

Searching & Availability

What is the maximum number of hotel IDs I can include in a single Search request?

To ensure optimal performance, we recommend a maximum of 50 hotel IDs per request. Our platform is designed to intelligently batch these requests to the supplier, so you don't have to worry about managing the complexity. This allows you to get comprehensive results without sacrificing speed.

Does HotelGo have rate limits on API requests?

"Requests Per Minute" (RPM) limitations are controlled by the supplier for each client. We recommend discussing your projections with the supplier directly to ensure a smooth integration.

See more details: Rate limit.

How do guest nationality and residency affect pricing?

They can have a significant impact. Many suppliers use guest nationality and/or residency to offer special rates for certain markets as part of their commercial strategy. If you notice unexpected pricing based on nationality, or wish to configure this, you should consult the commercial agreement you have with your supplier.

What does the `Allotment` field in the Search response represent?

The Allotment field indicates the number of physical rooms of that specific type that are currently available for booking. Please note that the presence of this field depends on whether the supplier provides this level of inventory detail.

How are children and infants defined in the API?

Child ages must be between 0 and 17. We do not specify a fixed infants age range, as this information is directly handled based on the various hotel and supplier policies.

How to search for multiple rooms with different occupancies? For example, having 1 adult in one room and 2 adults in another.

If the same guest wants to book 2 rooms in a single request, with one room for 1 adult and the other for 2 adults, you should enter the maximum number of adults across the different rooms for each room. In this case, you should enter 2 adults.

What's the difference between HotelList and HotelRates?

HotelList: Returns hotel candidates with basic information and optional pricing

HotelRates: Provides detailed room types and authoritative pricing information of the single specified hotel

Best Practice: Use HotelList for discovery, HotelRates for actual pricing

Rates & Booking

Does the response include a daily price breakdown?

No, our responses do not break down the average daily price breakdown. Generally, we have noticed most suppliers offer this as an average nightly rate of the total rate. If you see a use case for this, please reach out to us.

When searching multi-rooms, can I book rooms separately?

No, and this is by design to ensure booking integrity. Room rates returned in the response represents a complete, guaranteed package of rooms that must be booked together.

Does the API support "on request" or non-instant bookings?

No. Our platform and API are built exclusively for real-time, instantly confirmable inventory. This is a core part of our philosophy to ensure a fast, reliable, and seamless booking experience for the end user and to eliminate the uncertainty of "on request" offers.

How do I get the final Hotel Confirmation Number (HCN)?

After a successful booking, our API provides it.
In many cases, the official Hotel Confirmation Number (HCN) is returned directly in the booking response. However, if it is not immediately available, you can reliably retrieve it by calling our QueryOrders endpoint with the platform or supplier or customer (your) reference.

What are the different rate types returned by the API?

Our API can return several rate types to support various commercial models. Here are the most common:

netRate: This is the base cost of the room you are being charged by the supplier. It is non-commissionable.

commissionableRate: If you operate on a commission model, this is the rate from which your commission is calculated. Net rates are also included for commisionable rates.

grossRate: This typically represents the suggested retail price (SRP) or the hotel's best available rate.

respectGrossRate: A flag indicating whether you are contractually obligated to display or pass on the grossRate without modification.

🥇

Tip: Always ensure that your selling practices align with the SRP guidelines to avoid potential violations and contractual issues with suppliers

General

How do I get API credentials?

For testing, use the provided test credentials:

appKey: hotelbyte_api_demo

appSecret: hotelbyte_api_demo

For production, contact support@hotelbyte.com.

Is my data secure?

Yes, we use:

HTTPS encryption for all API calls

JWT token authentication

Secure storage of credentials

Rate limiting to prevent abuse

What's the correct API flow?

Authentication Get JWT token

Hotel rates/Hotel Search Find available hotels

Hotel rates/Rate Discovery Get detailed pricing

Make bookings/Availability Check Validate selected room

Make bookings/Booking Creation Create reservation

Manage bookings/Order Management Track bookings

Why do I need Session-Id?

Session-Id maintains context across your search and booking flow, ensuring:

Pricing consistency

Availability stability

What is ratePkgId?

ratePkgId is a unique identifier for room rate packages. You must validate it via CheckAvail before booking.

What does error 404 mean?

Resource not found

Invalid hotel ID or ratePkgId

Expired session

What does error 429 mean?

Rate limit exceeded

Too many requests

Wait and retry with exponential backoff

What does error 500 mean?

Internal server error

Retry with the same request parameters

Contact support if persistent

How can I improve performance?

Cache JWT tokens

Reuse Session-Id across related requests

Implement proper error handling and retries

Use pagination for large result sets

How do I test my integration?

Use our sandbox environment:

Base URL: https://api-test.hotelbyte.com

Test credentials provided

Specify Test header to cover more scenarios. See Test More Scenarios Guide

When can I go to production?

When you have:

Completed all test scenarios

Implemented proper error handling

Set up monitoring and logging

Received production credentials

Are there taxes and fees?

Yes, taxes are included in:

rates[i].tax.total: Total tax amount

rates[i].tax.items[]: Detailed tax breakdown

How do I cancel a booking?

Use the /api/trade/cancel endpoint with the order ID. Cancellation policies vary by supplier.

How do I check booking status?

Use /api/trade/queryOrders with your customerReferenceNo or supplierReferenceNo.

What happens if a booking fails?

Retry with the same customerReferenceNo for idempotency, then verify status via QueryOrders.

What information should I include in support requests by email?

API endpoint and method

Request parameters and headers

Complete error response

Request ID and timestamp

Your integration context

Frequently Asked Questions (FAQ)

Frequently Asked Questions (FAQ)#

Searching & Availability#

What is the maximum number of hotel IDs I can include in a single Search request?#

Does HotelGo have rate limits on API requests?#

How do guest nationality and residency affect pricing?#

What does the Allotment field in the Search response represent?#

How are children and infants defined in the API?#

How to search for multiple rooms with different occupancies? For example, having 1 adult in one room and 2 adults in another.#

What's the difference between HotelList and HotelRates?#

Rates & Booking#

Does the response include a daily price breakdown?#

When searching multi-rooms, can I book rooms separately?#

Does the API support "on request" or non-instant bookings?#

How do I get the final Hotel Confirmation Number (HCN)?#

What are the different rate types returned by the API?#

General#

How do I get API credentials?#

Is my data secure?#

What's the correct API flow?#

Why do I need Session-Id?#

What is ratePkgId?#

What does error 404 mean?#

What does error 429 mean?#

What does error 500 mean?#

How can I improve performance?#

How do I test my integration?#

When can I go to production?#

Are there taxes and fees?#

How do I cancel a booking?#

How do I check booking status?#

What happens if a booking fails?#

What information should I include in support requests by email?#

Frequently Asked Questions (FAQ)

Searching & Availability

What is the maximum number of hotel IDs I can include in a single Search request?

Does HotelGo have rate limits on API requests?

How do guest nationality and residency affect pricing?

What does the `Allotment` field in the Search response represent?

How are children and infants defined in the API?

How to search for multiple rooms with different occupancies? For example, having 1 adult in one room and 2 adults in another.

What's the difference between HotelList and HotelRates?

Rates & Booking

Does the response include a daily price breakdown?

When searching multi-rooms, can I book rooms separately?

Does the API support "on request" or non-instant bookings?

How do I get the final Hotel Confirmation Number (HCN)?

What are the different rate types returned by the API?

General

How do I get API credentials?

Is my data secure?

What's the correct API flow?

Why do I need Session-Id?

What is ratePkgId?

What does error 404 mean?

What does error 429 mean?

What does error 500 mean?

How can I improve performance?

How do I test my integration?

When can I go to production?

Are there taxes and fees?

How do I cancel a booking?

How do I check booking status?

What happens if a booking fails?

What information should I include in support requests by email?