Travel To Discover

Loading documentation…

Travel To Discover

3. API Reference

Export .md

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:

  1. Book returns a timeout or network error.
  2. Poll once immediately. If an order comes back, stop - the booking almost certainly went through.
  3. If nothing is returned, wait 30 seconds and poll again.
  4. Still nothing: wait 1 minute, then 2 minutes, doubling each time, up to a 10 minute ceiling.
  5. Inspect the status on every response. A confirmed order is treated as a successful booking; a pending order means keep polling.
  6. 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

json
{
  "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

Example response

json
{
  "code": 0,
  "msg": "string",
  "data": {
    "orders": [
      {
        "status": 1,
        "statusRemark": "aborted",
        "checkIn": "2026-01-01",
        "checkOut": "2026-01-03",
        "nightCount": 0,
        "roomCount": 0,
        "bookingTime": "2026-01-01T10:00:00Z",
        "hotelConfirmNo": "123456",
        "holder": {
          "email": "johndoe@example.com",
          "firstName": "John",
          "lastName": "Doe",
          "phone": {
            "countryCode": "1",
            "number": "1234567890"
          }
        },
        "platformReferenceNo": "1234567890",
        "customerReferenceNo": "1234567890",
        "commissionableRate": {
          "currency": "USD",
          "amount": 0
        },
        "netRate": {
          "currency": "USD",
          "amount": 0
        },
        "grossRate": {
          "currency": "USD",
          "amount": 0
        },
        "respectGrossRate": false,
        "cancelTime": "2026-01-02T10:00:00Z",
        "cancelReason": "Customer requested cancellation",
        "refundedPrice": {
          "amount": 99,
          "currency": "USD"
        },
        "supplier": 20000001,
        "supplierReferenceNo": "string",
        "hotel": {
          "hotelId": "string",
          "destinationId": "0192f3a7-5c41-7e88-b3d2-9a1c4e6f0b57",
          "name": {
            "en": "Jumeirah Beach Hotel"
          },
          "rating": 4.5,
          "address": {
            "en": "Millenium Al Barsha"
          },
          "latlngCoordinator": {
            "google": {},
            "gaode": {}
          },
          "logoURL": "https://cdn.example.com/hotel/461850557_1.jpg"
        },
        "rooms": [
          {
            "roomTypeId": "string",
            "roomTypeName": {},
            "hotelId": "string",
            "rates": [],
            "ratePkgId": "string",
            "refundableMode": "full",
            "refundableUntil": "2006-01-02T15:04:05Z07:00",
            "cancelFees": [],
            "originalRoomNaming": {},
            "rate": {},
            "totalRate": {},
            "rateComment": "string",
            "includesPackaging": false,
            "checkIn": "2026-01-01",
            "checkOut": "2026-01-03",
            "board": {},
            "tax": {},
            "roomIndex": 0,
            "guests": [],
            "refundInfo": []
          }
        ]
      }
    ]
  }
}

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

bash
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/queryOrders
A ticket will be fetched with ttdbooking_api_demo.