3. API Reference
QueryOrders
POST /api/trade/queryOrders
Retrieves hotel booking orders using a set of optional filters, and acts as the authoritative check on the real state of an order after a Book call.
The primary operational role of this endpoint is reconciliation. When a Book call times out or fails at the network layer, the client has no way of knowing whether the reservation was actually created. Polling this endpoint with the customerReferenceNo settles that question and avoids duplicate reservations, unreconciled charges, and client/server state drift.
Recovering from a Book timeout or network failure
Do not immediately re-issue the Book call. Wait for backend processing to finish, then query here with the customerReferenceNo that was submitted to Book.
Processing timing:
- Book performs backend work after the HTTP call completes.
- Full completion normally lands within a 3-10 minute window.
- Back off exponentially between polls so that fast successes are detected quickly while slow ones are still given time to settle.
Suggested polling sequence:
- Book returns a timeout or network error.
- Poll once immediately. If an order comes back, stop - the booking almost certainly went through.
- If nothing is returned, wait 30 seconds and poll again.
- Still nothing: wait 1 minute, then 2 minutes, doubling each time, up to a 10 minute ceiling.
- Inspect the status on every response. A confirmed order is treated as a successful booking; a pending order means keep polling.
- If nothing has materialised after the 10 minute ceiling, re-issuing Book may be appropriate.
Backing off this way gives immediate detection of successful bookings, allows slower ones time to complete, keeps client resource use proportionate, and avoids hammering the platform with tight-loop queries.
Filters
Recommended:
- customerReferenceNos - the customer reference numbers supplied to Book. This is the filter to use for timeout recovery.
Optional:
- platformReferenceNos - platform-internal reference numbers (see note: not present in the request schema)
- supplierReferenceNos - reference numbers issued by the supplier
- statusList - restrict to specific order statuses (confirmed, cancelled, pending, and so on)
- checkInTimeWindow - restrict by check-in date range
- checkOutTimeWindow - restrict by check-out date range
- bookingTimeWindow - restrict by booking creation date range
- freeCancelTimeWindow - restrict by free-cancellation date range
- cancelledTimeWindow - restrict by cancellation date range
What comes back
Each matching order carries its full detail: current status, booking confirmation data, pricing, payment and cancellation detail, and supplier reference numbers.
Rate limiting
High-volume querying is rate limited and will return HTTP 429. Use the backoff strategy above rather than polling aggressively.
Typical uses
- Verifying order state after a network failure on Book
- Ongoing order tracking and monitoring
- Customer-service order lookups
- Confirming a booking went through
- Financial reconciliation and audit
Request headers
| Header | Required | Description |
|---|---|---|
Client-Request-Timestamp |
No | client request time(start to send request); unix timestamp |
IP |
No | client IP address, compatible with both IPv4 and IPv6 |
Language |
No | IETF BCP 47 language tag (see https://masonreview.com/posts/ietf-bcp-47-language-tags/), eg: "en", "en-US"; default "en-US" |
Market |
No | Point-of-sale market for this call, as an ISO 3166-1 alpha-2 country code. Required only when your account carries a market restriction: an allow-list cannot admit a market you have not stated, so such an account refuses calls that omit it. |
Request-Id |
No | for identifying the current request, it can't be duplicate |
Trace-Id |
No | for tracing a group of requests |
User-Ref |
No | Your own identifier for the person on whose behalf this call is made. Required only once named users have been authorised on your account, after which every call must identify one and is authorised against that user's scopes as well as the key's. |
Authorization |
Yes | starts with "Bearer ". got from Ticket response. Ticket doesn't need it |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
customerReferenceNos[] |
array |
No | customer reference numbers to search for |
supplierReferenceNos[] |
array |
No | supplier reference numbers to search for |
checkInTimeWindow |
TimeWindow | No | filters orders by check-in date range |
checkInTimeWindow.start |
string | No | |
checkInTimeWindow.end |
string | No | |
checkOutTimeWindow |
TimeWindow | No | filters orders by check-out date range |
checkOutTimeWindow.start |
string | No | |
checkOutTimeWindow.end |
string | No | |
bookingTimeWindow |
TimeWindow | No | filters orders by creation date range |
bookingTimeWindow.start |
string | No | |
bookingTimeWindow.end |
string | No | |
freeCancelTimeWindow |
TimeWindow | No | filters orders by free cancel date range |
freeCancelTimeWindow.start |
string | No | |
freeCancelTimeWindow.end |
string | No | |
cancelledTimeWindow |
TimeWindow | No | filters orders by cancellation date range |
cancelledTimeWindow.start |
string | No | |
cancelledTimeWindow.end |
string | No | |
statusList[] |
array |
No | filters orders by status |
Example request
{
"customerReferenceNos": [
"1234567890"
]
}Response
Successful calls return the standard envelope. code is 0 on success — check it rather than the HTTP status alone, because some business failures are delivered with HTTP 200.
| Field | Type | Required | Description |
|---|---|---|---|
code |
integer | No | |
msg |
string | No | |
data |
hotel.trade.protocol.QueryOrdersResp | No | |
data.orders[] |
array |
No | Orders contains the list of matching orders |
data.orders[].status |
OrderStatus | No | OrderStatus indicates the current status of the order Allowed: 0, 1, 2, 3, 4, 5. |
data.orders[].statusRemark |
string | No | |
data.orders[].checkIn |
string | No | CheckIn is the check-in date, defaults to current date |
data.orders[].checkOut |
string | No | CheckOut is the check-out date, defaults to 7 days from now |
data.orders[].nightCount |
integer | No | Number of nights for the stay |
data.orders[].roomCount |
integer | No | Number of rooms in the booking. NOTE: the source description for this field literally reads "CheckOut is the check-out date for the booking", which is a copy/paste error upstream - the field is an int64 count, not a date. |
data.orders[].bookingTime |
string | No | BookingTime is when the booking was created |
data.orders[].hotelConfirmNo |
string | No | HotelConfirmNo is the confirmation number from the hotel |
data.orders[].holder |
Holder | No | Holder contains the person who made the booking |
data.orders[].holder.firstName |
string | Yes | |
data.orders[].holder.lastName |
string | Yes | |
data.orders[].holder.email |
string | No | |
data.orders[].holder.phone |
Phone | No | |
data.orders[].platformReferenceNo |
string | No | PlatformReferenceNo is the internal platform order identifier |
data.orders[].customerReferenceNo |
string | No | CustomerReferenceNo is the unique order identifier from the customer |
data.orders[].commissionableRate |
Money | No | used for commission calculation |
data.orders[].commissionableRate.currency |
string | Yes | Currency code, e.g. "USD". |
data.orders[].commissionableRate.amount |
number | Yes | Monetary amount, e.g. "14.50". |
data.orders[].netRate |
Money | No | |
data.orders[].netRate.currency |
string | Yes | Currency code, e.g. "USD". |
data.orders[].netRate.amount |
number | Yes | Monetary amount, e.g. "14.50". |
data.orders[].grossRate |
Money | No | |
data.orders[].grossRate.currency |
string | Yes | Currency code, e.g. "USD". |
data.orders[].grossRate.amount |
number | Yes | Monetary amount, e.g. "14.50". |
data.orders[].respectGrossRate |
boolean | No | You should respect GrossRate if RespectGrossRate is true; default as false |
data.orders[].cancelTime |
string | No | CancelTime is when the booking was cancelled, if applicable |
data.orders[].cancelReason |
string | No | CancelReason contains the reason if the order was cancelled |
data.orders[].refundedPrice |
Money | No | RefundedPrice is the amount that has been refunded to the customer |
data.orders[].refundedPrice.currency |
string | Yes | Currency code, e.g. "USD". |
data.orders[].refundedPrice.amount |
number | Yes | Monetary amount, e.g. "14.50". |
data.orders[].supplier |
integer | No | |
data.orders[].supplierReferenceNo |
string | No | SupplierReferenceNo is the unique order identifier from the supplier. NOTE: the raw source description is "SupplierReferenceNo is the unique order identifier from the supplier\t// Supplier identifies which supplier processed this order" - a leaked Go struct-tag comment belonging to the adjacent "supplier" field. |
data.orders[].hotel |
OrderHotelInfo | No | hotel-specific information |
data.orders[].hotel.hotelId |
string | No | |
data.orders[].hotel.destinationId |
string | No | index |
data.orders[].hotel.name |
I18N | No | hotel name |
data.orders[].hotel.rating |
number | No | Rating, hotel rating, range [0.0, 5.0] |
data.orders[].hotel.address |
I18N | No | Localised string set. Keys are fixed language codes. |
data.orders[].hotel.latlngCoordinator |
LatlngCoordinator | No | |
data.orders[].hotel.logoURL |
string | No | |
data.orders[].rooms[] |
array |
No | detailed information for each booked room |
data.orders[].rooms[].roomTypeId |
string | Yes | standardized roomTypeId, e.g. "R001" |
data.orders[].rooms[].roomTypeName |
I18N | Yes | standardized room type name; if not recognized, we'll give a default name like "Standard Room" |
data.orders[].rooms[].hotelId |
string | Yes | hotelId, duplicate of parent HotelId for indicating identified room |
data.orders[].rooms[].rates[] |
array<hotel.supplier.domain.RoomRatePkg> | No | core structure, room offers under this room |
data.orders[].rooms[].ratePkgId |
string | Yes | used as key input for checkAvail & book APIs |
data.orders[].rooms[].refundableMode |
RefundableMode | No | Refundability of the rate package: full = RefundableModeFully - free cancellation partial = RefundableModePartially - partial cancellation no = RefundableModeNo - not refundable Allowed: full, partial, no. |
data.orders[].rooms[].refundableUntil |
string | No | RefundableMode is valid until RefundableUntil |
data.orders[].rooms[].cancelFees[] |
array<hotel.supplier.domain.ComputedCancelPolicyItem> | No | |
data.orders[].rooms[].originalRoomNaming |
OriginalRoomNaming | No | origin room naming fields from supplier |
data.orders[].rooms[].rate |
Rate | Yes | single room price for multiple nights |
data.orders[].rooms[].totalRate |
Rate | Yes | total price for multiple rooms (and multiple nights) |
data.orders[].rooms[].rateComment |
string | No | |
data.orders[].rooms[].includesPackaging |
boolean | No | Whether this is a packaged product (e.g., flight+hotel combo) |
data.orders[].rooms[].checkIn |
string | Yes | CheckIn is the check-in date, defaults to current date |
data.orders[].rooms[].checkOut |
string | Yes | CheckOut is the check-out date, defaults to 7 days from now |
data.orders[].rooms[].board |
Board | No | Board info - Standard meal plan following liteapi standard |
data.orders[].rooms[].tax |
Tax | No | Taxes and fees, generally collected by hotels on behalf of the government, are fixed costs and do not participate in the price increase during the distribution process. Therefore, they are listed separately. |
data.orders[].rooms[].roomIndex |
integer | No | room index |
data.orders[].rooms[].guests[] |
array |
No | information about all guests in this room |
data.orders[].rooms[].refundInfo[] |
array<hotel.supplier.domain.OrderRoomRefundInfo> | No |
Failure responses
| HTTP | Meaning |
|---|---|
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 429 | Too many requests |
Every failure uses the { code, msg } envelope. See Error handling for the full business-code table.
Code samples
curl -X POST https://api-test.ttdbooking.com/api/trade/queryOrders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TICKET" \
-H "Request-Id: $(uuidgen)" \
-d '{
"customerReferenceNos": [
"1234567890"
]
}'Try it
Try it
POST /api/trade/queryOrdersA ticket will be fetched with ttdbooking_api_demo.