QueryOrders

Query hotel booking orders with comprehensive filtering and critical post-booking verification.

This endpoint provides essential order status verification capabilities, particularly crucial
for handling booking timeouts and network errors. It enables comprehensive order tracking
and status confirmation to prevent financial losses and booking conflicts.

Critical Usage for Network Error Recovery:
ESSENTIAL: If Book API encounters timeout or network errors, wait for processing completion
then call QueryOrders with the customerReferenceNo to verify order status.

Important Processing Timeline:

Book API requires processing time to complete all backend operations

Typical processing window: 3-10 minutes for full completion

Use exponential backoff strategy for optimal response time

This balances quick detection with processing completion assurance

This approach prevents:

Double bookings due to unclear order state

Financial losses from unconfirmed transactions

Customer service issues from booking uncertainties

Data inconsistency between client and server

Recommended Parameters:

customerReferenceNos: Customer reference numbers from Book API (recommended for timeout recovery)

Optional Filtering Criteria:

platformReferenceNos: Platform internal reference numbers

supplierReferenceNos: Supplier-generated reference numbers

statusList: Filter by order status (confirmed, cancelled, pending, etc.)

checkInTimeWindow: Filter by check-in date range

checkOutTimeWindow: Filter by check-out date range

bookingTimeWindow: Filter by booking creation date range

freeCancelTimeWindow: Filter by free cancel date range

cancelledTimeWindow: Filter by cancellation date range

Response Features:

Complete order details with current status

Booking confirmation information

Payment and cancellation details

Supplier reference numbers

Network Error Recovery Workflow:

Book API returns timeout/network error

Implement exponential backoff retry strategy:

Immediately call QueryOrders once (quick detection)

If order found: Stop - booking likely succeeded

If no order: Wait 30 seconds, retry

If still no order: Wait 1 minute, retry

If still no order: Wait 2 minutes, retry

Continue doubling wait time up to 10 minutes maximum

Check order status in each response

If confirmed: Process as successful booking

If pending: Continue retry cycle

If failed after 10 minutes: Retry Book API if appropriate

Exponential Backoff Benefits:

Immediate detection of successful bookings

Gradual increase in wait time for processing completion

Efficient resource usage with balanced response time

Prevents overwhelming the system with rapid queries

Rate Limiting:

Subject to rate limiting for high-volume queries

Returns 429 error for excessive requests

Use judiciously during error recovery scenarios

Common Use Cases:

Post-booking status verification after network errors

Order status tracking and monitoring

Customer service order inquiries

Booking confirmation verification

Financial reconciliation and auditing

curl --location --request POST 'https://api-test.hotelbyte.com/api/trade/queryOrders' \ --header 'Client-Request-Timestamp;' \ --header 'IP;' \ --header 'Language;' \ --header 'Request-Id;' \ --header 'Trace-Id;' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "customerReferenceNos": [ "string" ], "supplierReferenceNos": [ "string" ], "checkInTimeWindow": { "start": "2006-01-02T15:04:05Z07:00", "end": "2006-01-02T15:04:05Z07:00" }, "checkOutTimeWindow": { "start": "2006-01-02T15:04:05Z07:00", "end": "2006-01-02T15:04:05Z07:00" }, "bookingTimeWindow": { "start": "2006-01-02T15:04:05Z07:00", "end": "2006-01-02T15:04:05Z07:00" }, "freeCancelTimeWindow": { "start": "2006-01-02T15:04:05Z07:00", "end": "2006-01-02T15:04:05Z07:00" }, "cancelledTimeWindow": { "start": "2006-01-02T15:04:05Z07:00", "end": "2006-01-02T15:04:05Z07:00" }, "statusList": [ 0 ] }'

{ "code": 0, "msg": "string", "data": { "orders": [ { "status": 0, "statusRemark": "aborted", "checkIn": "now()", "checkOut": "now()+7", "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", "hotel": { "hotelId": "string", "destinationId": "804028047", "name": { "en": "Jumeirah Beach Hotel" }, "rating": 4.5, "address": { "en": "Millenium Al Barsha" }, "latlngCoordinator": { "google": { "lat": 25.0478, "lng": 121.5319 }, "gaode": { "lat": 25.0478, "lng": 121.5319 } }, "logoURL": "https://static.hotelbyte.com/Images/Hotel/804028047_1.jpg" }, "rooms": [ { "roomTypeId": "string", "roomTypeName": { "en": "string", "zh": "string", "ar": "string" }, "hotelId": "string", "rates": [ { "ratePkgId": "string", "refundableMode": "full", "refundableUntil": "2006-01-02T15:04:05Z07:00", "cancelFees": [ { "until": "2006-01-02T15:04:05Z07:00", "fee": { "currency": "string", "amount": 0 } } ], "originalRoomNaming": { "id": "string", "name": "string", "supplier": 0 }, "rate": { "commissionableRate": { "currency": "string", "amount": 0 }, "netRate": { "currency": "string", "amount": 0 }, "grossRate": { "currency": "string", "amount": 0 }, "respectGrossRate": true }, "totalRate": { "commissionableRate": { "currency": "string", "amount": 0 }, "netRate": { "currency": "string", "amount": 0 }, "grossRate": { "currency": "string", "amount": 0 }, "respectGrossRate": true }, "rateComment": "string", "includesPackaging": true, "checkIn": "now()", "checkOut": "now()+7", "board": { "boardId": "RO", "boardName": { "en": "string", "zh": "string", "ar": "string" }, "boardDesc": { "en": "string", "zh": "string", "ar": "string" } }, "tax": { "total": { "currency": "string", "amount": 0 }, "items": [ { "taxType": "string", "taxName": "string", "amount": { "currency": "string", "amount": 0 }, "desc": "string" } ] } } ], "ratePkgId": "string", "refundableMode": "full", "refundableUntil": "2006-01-02T15:04:05Z07:00", "cancelFees": [ { "until": "2006-01-02T15:04:05Z07:00", "fee": { "currency": "string", "amount": 0 } } ], "originalRoomNaming": { "id": "string", "name": "string", "supplier": 0 }, "rate": { "commissionableRate": { "currency": "string", "amount": 0 }, "netRate": { "currency": "string", "amount": 0 }, "grossRate": { "currency": "string", "amount": 0 }, "respectGrossRate": true }, "totalRate": { "commissionableRate": { "currency": "string", "amount": 0 }, "netRate": { "currency": "string", "amount": 0 }, "grossRate": { "currency": "string", "amount": 0 }, "respectGrossRate": true }, "rateComment": "string", "includesPackaging": true, "checkIn": "now()", "checkOut": "now()+7", "board": { "boardId": "RO", "boardName": { "en": "string", "zh": "string", "ar": "string" }, "boardDesc": { "en": "string", "zh": "string", "ar": "string" } }, "tax": { "total": { "currency": "string", "amount": 0 }, "items": [ { "taxType": "string", "taxName": "string", "amount": { "currency": "string", "amount": 0 }, "desc": "string" } ] }, "roomIndex": 0, "guests": [ { "roomIndex": 0, "firstName": "John2", "lastName": "Doe", "nationalityCode": "US", "age": 18, "isChild": false } ], "refundInfo": [ { "date": "string", "refunded": true, "refundedMoney": { "currency": "string", "amount": 0 } } ] } ] } ] } }

Request

Responses