Hotels API

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.

GET/booking/{bookingReference}/accommodations/{accommodationBookingReference}

Stored data only, no supplier call

Booking detail returns what the platform has stored for the hotel. It does not contact the supplier, so it is cheap and changes nothing. Use it for routine polling. To ask the supplier for the latest state, use Refresh, which calls the supplier. Test suppliers may not answer a Refresh like real suppliers, so ask your Nava account manager how they respond before your tests rely on it. Unverified

Request

Headers

auth-tokenstringrequired
Any valid token.
Accept-EncodingstringrequiredDocs
gzip

Path

bookingReferencestringrequired
Trip reference from the Book response, for example TST-1464.
accommodationBookingReferencestringrequiredTested
Service reference from the Book response (accommodation.bookingReference), for example TST-1464-0. The supplier's reference (hotelservice[].bookingReference in getBookings) is accepted too.

Response

The same shape as the Book response. Spec The fields you will use most:

200 OK

bookingReferencestring
Trip reference.
statusServiceStatus
Booking-level status, derived from the service statuses.
externalReferencestringSpec
Your order id, as you sent it to Book. getBookings returns it as agencyBookingReference. Tested
accommodationobject

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

Child attributes
bookingReferencestring
Service reference.
statusServiceStatus
Service-level status of the hotel.
errorMessagestring
Why the booking failed, when it did.
combinationobject
Rooms, meal plan, price, cancellation policies and remarks as booked.
distributions[]DistributionVO[]
Guests 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).

Poll a booking on request

When Book returns RQ or PENDING_BOOK, the platform keeps checking with the supplier and updates the stored booking. Booking detail shows you that update without a supplier call of your own. Read both levels: status for the booking and accommodation.status for the hotel.

  • We recommend polling every 5 to 15 minutes, together with the MODIFIED and CANCELED webhooks. Unverified
  • Set a limit, for example 24 to 48 hours. After it, your operations team contacts your Nava account manager or the hotel. Unverified
  • Keep the guest on "Pending confirmation" until the status changes. Show "Confirmed" only for BOOKED.
RQ / PENDING_BOOKPending confirmation
The supplier hasn't confirmed yet.
Poll again on the next run.
BOOKEDConfirmed
The supplier confirmed.
Confirm the order and send the voucher.
CANCELED / NOT_BOOKEDNot confirmed
The supplier did not accept the booking.
Tell the guest and refund if you charged.
BOOK_ERRORNot confirmed
The booking failed.
Operators sometimes fix a failed booking and it becomes BOOKED, so check it again later before you close the order. Verified
PRICE_ERRORUnder review
Booked at a different closing price.
Escalate to your operations team. It can be transient or stay stored. Verified
Anything elseChecking status
A status outside the documented outcomes.
Route it to a person. Never treat it as success.

Read back your order id

The externalReference you sent to Book is stored on the booking and returned here under that name. The trip returned by getBookings carries the same value as agencyBookingReference. Tested Either works when you reconcile a Book call that timed out. See If Book times out.

If you start from getBookings, use hotelservice[].id as the accommodationBookingReference for this path: it is the value Book returned as accommodation.bookingReference. The supplier's hotelservice[].bookingReference works too. Tested

Errors

The spec documents no error schema and no status codes. Spec Treat any non-2xx response as a failure, and keep the raw body, the trace id and the x-request-id header. A 404 body carries auditData with the trace id; this GET sends no Travelc-Trace-Id header. Tested

StatusMeaningWhat to do
404Booking reference not found: the reference doesn't exist in this microsite. Tested It is not an outage. Verified A fake booking always returns 404 here, because it is never saved. TestedCheck both references and the credentials' microsite.
401 / 403Token rejected. VerifiedRe-authenticate once, then alert.
5xx, 429, timeoutTemporary failure. VerifiedRetry with backoff. Safe here because the call changes nothing.

Gotchas

  • Bookings made with fakeBooking are not saved, so booking detail on one will probably fail. Test post-booking calls on real bookings in your test account. Unverified
  • Every response echoes your live token in auditData.authToken. Redact it before you log or store the payload.
  • A booking can close RQ even when onRequest was false throughout the flow, so poll every non-final status, not only the ones you expected. Verified
  • Book: the response shape and every field
  • Refresh: ask the supplier for the latest state (not for routine polling)
  • Booking statuses: the two status levels
  • Webhooks: react to changes instead of polling

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.

Refresh

Ask the supplier for the current state of a booked hotel and return the updated booking. Use it to resolve a booking on request or to detect a cancellation made on the supplier's side, not for routine polling.