Hotels API

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.

PUT/booking/{bookingReference}/accommodations/{accommodationBookingReference}

Refresh calls the supplier: poll with booking detail

Use booking detail (GET) for routine polling; Refresh calls the supplier. Booking detail reads stored data and makes no supplier call. Docs Some test suppliers report every refreshed booking as CANCELED, which real suppliers don't do, so don't Refresh a test booking you still need. Confirmed

Request

Headers

auth-tokenstringrequired
Any valid token.
Accept-EncodingstringrequiredDocs
gzip

Path

bookingReferencestringrequired
Trip reference from the Book response.
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.

There is no request body.

Response

The same shape as the Book response, with the status the supplier reported. Spec If the supplier reports no change, the booking comes back as it was. Confirmed

200 OK

bookingReferencestring
Trip reference.
statusServiceStatus
Booking-level status after the refresh.
externalReferencestring
Your order id.
accommodationobject

The booked hotel.

Child attributes
bookingReferencestring
Service reference.
statusServiceStatus
Service-level status after the refresh.
errorMessagestring
Why the booking failed, when it did.
combinationobject
Rooms, meal plan, price, cancellation policies and remarks.
distributions[]DistributionVO[]
Guests. The array key is person.
auditDataAuditResponseVO
Includes traceId (one per token: log it) and authToken (redact it before logging).

When to use it

SituationCall
Routine polling of a booking on requestBooking detail. The platform already polls the supplier for you.
A booking stays RQ longer than your limit and you want the supplier's answer nowRefresh.
You suspect the supplier cancelled the booking on their sideRefresh.
Cancel timed out and booking detail still shows the booking activeRefresh, before you decide whether to cancel again.
Reading bookings in your test accountBooking detail. A test supplier may answer a Refresh with CANCELED; ask your Nava account manager how yours respond. Confirmed

Behaviour

  • Refresh asks the supplier for the booking's current status and returns it in the Book response shape. Confirmed
  • No change at the supplier: the booking comes back unchanged. Confirmed
  • A supplier that doesn't support refreshing makes the call fail with 406. Confirmed Don't retry it: read booking detail instead.
  • Some test suppliers answer every Refresh with CANCELED. That is a property of the test supplier, not of Refresh. Confirmed
  • A refreshed booking that comes back CANCELED in production means the booking is no longer valid. Tell the guest, reverse your accounting and refund if you charged. Follow the same path as a CANCELED webhook.

Errors

The spec documents no error schema and no status codes. Treat any non-2xx response as a failure and keep the raw body and the trace id. Spec

StatusMeaningWhat to do
404The reference doesn't exist (in this microsite). VerifiedCheck both references and the microsite.
406The supplier doesn't support refreshing. ConfirmedDon't retry. Use booking detail.

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.

Cancel

Cancel a booked hotel at the supplier. The response returns the booking with status CANCELED. Cancel is not safely retryable, and it does not refund the guest.