Hotels API

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.

DEL/booking/{bookingReference}/accommodations/{accommodationBookingReference}

Never retry Cancel automatically

Cancel acts at the supplier and is not safely retryable. After a timeout, read Booking detail first (and Refresh if needed) before you try again. See If Cancel times out.

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.

There is no request body. Get the penalty from Cancellation fee and the guest's consent before you call Cancel.

Response

The same shape as the Book response. Spec A successful cancel shows CANCELED at both levels. Docs

200 OK

bookingReferencestring
Trip reference.
statusServiceStatus
Booking-level status. CANCELED on success.
externalReferencestring
Your order id.
accommodationobject

The cancelled hotel.

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

A guest cancels

Call Cancellation fee and show the guest what cancelling today costs.

Get the guest's consent to that fee.

Call Cancel once. Allow at least 120 seconds: the docs example took about 9 seconds. Docs

Check that status and accommodation.status are both CANCELED.

Refund the guest what they paid minus the fee. Use Refund if the platform holds the payment, or your own payment provider if you charged the guest yourself. A REFUND webhook fires when a platform refund succeeds. Docs

Cancel does not refund the guest. Refunds are a separate call.

Check the result

CANCELEDCancelled
Cancelled at the supplier, at both levels.
Close the order and start the refund. Docs
Anything elseCancellation in progress
Not confirmed as cancelled. The full enum also has values such as CANCEL_ERROR.
Route it to a person. Don't call Cancel again until someone has checked the booking. Spec
TimeoutCancellation in progress
No response. The supplier may or may not have cancelled.
Don't retry. Reconcile first.

If Cancel times out

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

Don't call Cancel again yet.

Read Booking detail. If both statuses are CANCELED, the cancel went through: continue with the refund.

If detail still shows the booking active, call Refresh to read the supplier's state. A 406 means the supplier doesn't support refreshing: rely on booking detail and ask your Nava account manager. Confirmed When you rehearse this path in your test account, test suppliers may not behave exactly like real suppliers after Refresh or Cancel, so ask your Nava account manager how they respond. Unverified

Only if the supplier still holds the booking, check the fee again and call Cancel once more.

Gotchas

  • A 200 response is not proof of cancellation. Check both status fields.
  • The fee can change from one day to the next as policy dates pass, so quote it right before you cancel.
  • Bookings made with fakeBooking are not saved, so Cancel on one will probably fail. Test on real bookings in your test account. Unverified
  • The generic Cancel service also takes a MANUAL type and a manual fee, most likely for a cancellation handled outside the platform. Unverified

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.

Cancellation fee

Get the penalty a booked hotel would cost if you cancelled it today. It is a read-only quote. It cancels nothing and refunds nothing.