Skip to content

4. FAQ - Quote & Booking

Why do I need to confirm before booking?

Prices and availability from a search can change. The confirm step (POST /options/{option_uid}/actions/confirm) checks the option with the hotel again, returns its current details, and tells you which guest details the booking needs. Book the returned confirmation_uid soon afterwards.

What does price_tolerance mean? (Deltaprice)

price_tolerance is the price increase you accept between search and confirmation, or between confirmation and booking, as a whole percentage. With "price_tolerance": 5, the booking goes ahead if the price rose by at most 5%.

  • Send it in the JSON body of the confirm and book requests.
  • If you leave it out or send 0, a default tolerance applies (5% for most hotels).
  • If the price rose by more, the request fails with HTTP 409 Conflict and a message stating the new price. Search again, or retry with a higher tolerance.

Which guest details do I need to send?

The confirm response lists them: required_fields_holder for the booking holder and required_fields_guests for each guest. First and last name are always required. List the guests in the order of the occupancy; if the holder is staying, include them as the first guest as well.

What is the client reference?

client_reference is your own reference for the booking, for example your order number. It can be any string. Send it in the JSON body of the book request; it is returned in reference.client of the booking, so you can match bookings to your own records.

Can I send remarks to the hotel?

Yes, in the remarks field of the book request body. Remarks are requests, not guarantees.

The booking status is PENDING. What does that mean?

PENDING means your booking request reached the hotel's reservation system, but the outcome isn't confirmed yet: the hotel's answer was lost, or it arrived too late.

A pending booking is not an error. ApiXV keeps it open under its booking_uid and checks with the hotel automatically, at increasing intervals and in any case before the free-cancellation deadline. As soon as the outcome is known, the status changes:

  • BOOKED: the hotel holds the booking. The hotel's reference is in reference.supplier.
  • FAILED: no booking was made. You can book again.

While a booking is pending:

  1. Keep the booking_uid and treat the booking as made: tell your customer it is being confirmed.
  2. Don't book the same stay again. A second booking request for the same hotel, dates and lead guest is refused with 409 Conflict while the first one is pending; the message names the pending booking_uid.
  3. Poll GET /hotelxv/api/v2/bookings?booking_uids=<booking_uid> until the status is BOOKED, FAILED or CANCELLED.
  4. If the customer no longer wants the stay, send the cancel request anyway. It is refused with 409 Conflict while the outcome is unknown, but your request is recorded: if the booking turns up and can still be cancelled free of charge, we cancel it for you (status CANCELLED); otherwise it becomes BOOKED and you cancel it in the usual way.