Hotels API

Book

Close the booking with the supplier, using the key from Prebook. The status in the response tells you whether the room is confirmed. A 200 response on its own does not.

POST/booking/accommodations/{accommodationId}/book

Never retry Book automaticallySpec

Book has no idempotency key. A call that timed out may still have booked, and a retry can book the room twice. See If Book times out.

Request

Headers

auth-tokenstringrequired
The same token you used for Quote.
Accept-EncodingstringrequiredDocs
gzip
Content-Typestringrequired
application/json

Path

accommodationIdstringrequired
Hotel code from the Quote response, for example MASTER-1782232.

Body

accommodationobjectrequired

The offer to book.

Child attributes
combinationKeystringrequired
The key from the Prebook response. Treat it as an opaque string of any length and don't store it long term.
externalReferencestring, max 50Spec
Your own order id. Save it before calling Book so you can reconcile a timeout. Booking detail returns it as externalReference; getBookings returns it as agencyBookingReference. Tested
fakeBookingobjectDocs

Testing only. Forces the outcome. A fake booking is not saved and not sent to suppliers, even in production.

Child attributes
statusServiceStatus
BOOKED or BOOK_ERROR. See fakeBooking.

Response

The same shape is returned by Booking detail, Refresh and Cancel.

200 OK

bookingReferencestring
Trip reference, for example TST-1464. Needed for every post-booking call.
statusServiceStatus
Booking-level status. Branch on it.
externalReferencestring
Echo of your order id.
accommodationobject

The booked hotel: code, giataId, name, category, geolocation, checkIn, checkOut and the fields below.

Child attributes
bookingReferencestringTested
Service reference, for example TST-1464-0. Also needed for post-booking calls. In getBookings it is hotelservice[].id; the supplier's own reference is hotelservice[].bookingReference there.
statusServiceStatus
Service-level status.
errorMessagestring
Why the booking failed, when it did.
combinationobject
Rooms, meal plan, price, cancellation policies, remarks and commentToAccommodation as booked. There is no combinationKey any more.
distributions[]DistributionVO[]
Guests, now with ids like TST-1464-0-1 (booking, room, person). The array key is person.
auditDataAuditResponseVO
Includes traceId (one per token: log it) and authToken (redact it before logging).

Save these immediately

bookingReference, accommodation.bookingReference, your externalReference and auditData.traceId. Every post-booking call needs both references, and support will ask for the trace id.

Branch on the status

Keep what the guest sees separate from the API status. Show "Confirmed" only for BOOKED. Treat any status not listed here as "needs a person", never as success. More detail in Booking statuses.

BOOKEDConfirmed
Confirmed by the supplier.
Save both references and send the confirmation.
RQPending confirmation
On request. The supplier hasn't confirmed yet.
Poll booking detail every few minutes, or wait for a webhook. This can happen even when onRequest was false throughout the flow. Verified
PENDING_BOOKPending confirmation
Still being processed.
Handle it like RQ.
PRICE_ERRORUnder review
Booked, but the closing price moved beyond the tolerance (0.5% by default).
Escalate to your operations team to accept or cancel. Docs
BOOK_ERRORNot confirmed
The booking failed.
Show accommodation.errorMessage and offer a new search. Check booking detail later: operators sometimes fix it and it becomes BOOKED. Verified
NOT_BOOKEDNot confirmed
The supplier refused.
Offer a new search.
TimeoutChecking status
No response. The outcome is unknown.
Don't retry. Reconcile first.

If Book times out

A suggested reconciliation sequence. It is a design recommendation, not a documented procedure. Unverified

Wait a minute. Your externalReference is already saved.

List today's bookings with GET /booking/bookings. Each entry carries its bookingReference and status.

Read each candidate with getBookings and compare its agencyBookingReference with your externalReference, then the hotel code and dates. Tested

Only if nothing matches, and the key (60 minutes) and token are still valid, call Book again with the same key. Otherwise start again from Quote and tell the guest.

Simulate outcomes with fakeBooking

Add fakeBooking: { "status": "BOOK_ERROR" }, or BOOKED, to the Book request to rehearse an outcome without involving a supplier. Docs

  • The response is HTTP 200 with the status you asked for, which is one more reason to branch on status and never on the HTTP code. A BOOK_ERROR carries accommodation.errorMessage, Booking not confirmed. BOOK_ERROR. Tested
  • The references are made up for the occasion: bookingReference looks like FAKE-1043 and accommodation.bookingReference like FAKE-ACCOMMODATION-1043. Tested
  • Nothing is saved and nothing reaches a supplier, even in production. Docs Booking detail answers 404 Booking reference not found for a fake booking, so test post-booking calls on real bookings in your test account. Tested

Testing

  • Test suppliers may not behave exactly like real suppliers, so don't assume a test booking closes BOOKED. Ask your Nava account manager how they respond. Unverified
  • Use fakeBooking to rehearse BOOK_ERROR, and real test bookings for everything after Book.

Prebook

Send the guests' details and re-validate the offer with the supplier. Prebook returns the combinationKey for Book, so compare its offer with Confirm before you book.

Booking detail

Read a booked hotel from the platform's stored data, without a call to the supplier. Use it to poll bookings that are on request and to read back your own order id.