1. Get started
Frequently Asked Questions (FAQ)
This page collects the questions that come up most often while integrating with the TTDbooking API, covering how the API behaves, how to use it well, and the commercial rules behind the rates it returns.
Searching & Availability
How many hotel IDs can one Search request carry?
Keep each request to 50 hotel IDs or fewer. Larger ID sets degrade response times, so split anything bigger across multiple requests.
Does TTDbooking enforce request rate limits?
Yes. Each endpoint carries a per-second ceiling, counted per endpoint per client IP: 100/second on search and content, 50/second on QueryOrders, 10/second on CheckAvail, Book and Cancel, and 5/second on ticket issuance.
Share your expected traffic volumes with us before go-live so your account is sized correctly. For the full picture — including the X-RateLimit-* headers on every response — see the Rate limit guide.
Why do guest nationality and residency change the price?
Because suppliers price on them. Nationality and residency are common levers for market-specific rates, so the same room can return different prices depending on the values you send. If the pricing you see doesn't match what you expect — or you want these rates switched on — check the commercial agreement you hold with the supplier.
What is the Allotment field in a Search response?
Allotment is the count of physical rooms of that room type still open for booking. Not every supplier publishes inventory at this level of detail, so the field is not guaranteed to be present in every response.
How does the API define children and infants?
Child ages are accepted in the range 0 to 17. There is no fixed infant age band in the API — infant handling follows each hotel's and supplier's own policy.
How do I search several rooms with different occupancies, such as 1 adult in one room and 2 adults in another?
Send the highest adult count of any room, applied to every room. For a two-room request where one room holds 1 adult and the other holds 2, submit 2 adults for both rooms.
What's the difference between HotelList and HotelRates?
| Endpoint | What it returns | Use it for |
|---|---|---|
| HotelList | Candidate hotels with basic information and optional pricing | Discovery — narrowing a destination down to a shortlist |
| HotelRates | Detailed room types and authoritative pricing for one specified hotel | Actual pricing — the numbers you show and book against |
Best practice: run HotelList to discover, then HotelRates to price.
Rates & Booking
Is there a day-by-day price breakdown in the response?
No. Responses do not split the stay into nightly amounts. Suppliers generally express nightly pricing as an average of the total rate rather than as true per-date pricing. If your product needs a daily breakdown, tell us about the use case.
On a multi-room search, can I book the rooms one at a time?
No — this is deliberate, and it protects booking integrity. The rates returned for a multi-room search describe one complete, guaranteed package of rooms, and that package has to be booked as a unit.
Does the API support "on request" (non-instant) bookings?
No. The API works only with real-time, instantly confirmable inventory. Everything returned can be confirmed immediately, which removes the wait-and-see uncertainty that comes with on-request offers.
How do I obtain the Hotel Confirmation Number (HCN)?
The API returns it once the booking succeeds. The official HCN is frequently included in the booking response itself. When it isn't yet available at that moment, call the QueryOrders endpoint using the platform reference, the supplier reference, or your own customer reference to fetch it.
Which rate types can the API return?
Several rate types are supported so that different commercial models can be represented:
| Rate type | Meaning |
|---|---|
netRate |
The base cost of the room charged to you by the supplier. Non-commissionable. |
commissionableRate |
For commission-based models, the rate your commission is calculated from. Net rates are also included alongside commissionable rates. |
grossRate |
Usually the suggested retail price (SRP), or the hotel's best available rate. |
respectGrossRate |
A flag showing whether you are contractually required to display or pass through the grossRate unchanged. |
🥇 Tip: Keep your selling prices in line with SRP guidance. Departing from it can put you in breach of your supplier contracts.
General
How do I get API credentials?
Test credentials are provided for the sandbox:
appKey:ttdbooking_api_demoappSecret:ttdbooking_api_demo
For production credentials, email integrations@ttdbooking.com.
Is my data secure?
Yes. The following protections are in place:
- HTTPS encryption on every API call
- JWT token authentication
- Secure storage of credentials
- Rate limiting to block abuse
What is the correct API flow?
- Authentication — obtain a JWT token
- Hotel rates / Hotel Search — find available hotels
- Hotel rates / Rate Discovery — retrieve detailed pricing
- Make bookings / Availability Check — validate the selected room
- Make bookings / Booking Creation — create the reservation
- Manage bookings / Order Management — track bookings
Why is Session-Id required?
Session-Id carries context from search through to booking. Holding that context is what gives you:
- Pricing consistency
- Availability stability
What is ratePkgId?
ratePkgId uniquely identifies a room rate package. Validate it through CheckAvail before you attempt to book.
What does a 404 error mean?
- The resource was not found
- The hotel ID or
ratePkgIdis invalid - The session has expired
What does a 429 error mean?
- The request ceiling for that endpoint has been exceeded —
msgsays what - If a
Retry-Afterheader is present, wait that many seconds; otherwise back off exponentially - Check
X-RateLimit-Remainingon your normal responses to see it coming - See the Rate limit guide
What does a 500 error mean?
- An internal server error occurred
- Retry using the same request parameters
- Contact support if it keeps happening
How can I improve performance?
- Cache JWT tokens
- Reuse the same
Session-Idacross related requests - Build in proper error handling and retries
- Paginate when result sets are large
How do I test my integration?
Work against the sandbox environment:
- Base URL:
https://api-test.ttdbooking.com - Test credentials provided
Send the Test header to unlock additional scenarios. See the Test More Scenarios Guide.
When am I ready for production?
Move to production once you have:
- Worked through all of the test scenarios
- Implemented proper error handling
- Put monitoring and logging in place
- Received your production credentials
Are taxes and fees included?
Yes. Tax figures are carried in:
rates[i].tax.total— the total tax amountrates[i].tax.items[]— the itemised tax breakdown
How do I cancel a booking?
Call the /api/trade/cancel endpoint with the order ID. Note that cancellation policies differ from supplier to supplier.
How do I check a booking's status?
Call /api/trade/queryOrders with either your customerReferenceNo or the supplierReferenceNo.
What should I do when a booking fails?
Retry using the same customerReferenceNo — that value is the idempotency key — then confirm the outcome through QueryOrders.
What should I include when emailing support?
Send your request to integrations@ttdbooking.com with:
- The API endpoint and HTTP method
- The request parameters and headers
- The complete error response
- The request ID and timestamp
- Background on your integration