Book

Place a hotel booking order to reserve a room for the specified rate package.

This endpoint executes the final step in the hotel booking flow, creating a confirmed reservation with the supplier. It handles pre-paid account deduction, order creation, and enterprise-grade reliability mechanisms.

Critical Prerequisites:

SessionId (REQUIRED in Header): Must be provided to track the booking process

Must be called after CheckAvail: Ensures rate package is still available

JWT Authentication: Bearer token required in Authorization header

Required Parameters:

customerReferenceNo: The reference number for the booking

ratePkgId: The rate package ID for the booking

holder: The holder information for the booking

guests: The guests information for the booking

sessionId (in Header): The session ID for tracking the booking process

Booking Flow Integration:

Search: Call HotelRates to get available room options

Select: User selects a specific rate package

Verify: Call CheckAvail to confirm availability and pricing

Book: Call Book to place the final reservation ← This step

Confirm: Query order status to verify booking success

Idempotency:

Requests are idempotent by customerReferenceNo

Duplicate requests with same identifiers return existing order

Prevents accidental double bookings

Enterprise Reliability Features:

Order status tracking and confirmation

Session management for booking context

Transaction rollback on failures

Response Features:

Confirmed booking details

Supplier reference numbers

Order tracking information

Error Handling:

Timeout errors for upstream/supplier delays

Enterprise reliability mechanisms for booking failures

Order rollback on critical failures

Common Use Cases:

Final hotel reservation confirmation

curl --location --request POST 'https://api-test.hotelbyte.com/api/trade/book' \ --header 'Client-Request-Timestamp;' \ --header 'Currency;' \ --header 'IP;' \ --header 'Language;' \ --header 'Request-Id;' \ --header 'Session-Id;' \ --header 'Test;' \ --header 'Timeout-Milliseconds;' \ --header 'Trace-Id;' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "customerReferenceNo": "uuid", "ratePkgId": "string", "holder": { "firstName": "John", "lastName": "Doe", "email": "John@hotelbyte.com", "phone": { "countryCode": "string", "countryNumber": 0, "number": "string" } }, "guests": [ { "roomIndex": 0, "firstName": "John2", "lastName": "Doe", "nationalityCode": "US", "age": 18, "isChild": false } ] }'

{ "code": 0, "msg": "string", "data": { "hotelOrder": { "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