Offers

An offer is one bookable result from Availability. It combines:

• a unit and a rate plan
• your dates and occupancy
• a price

You book an offer by putting its id in a reservation (Booking).

Lifetime

• An offer is valid for 1 hour after the search that produced it.
• After that, GET /offers/{id} returns 404 and a booking that uses it is rejected.
• An offer can stop being bookable before the hour is up if the hotel changes the price or policies or sells the unit. The hour is a maximum, not a guarantee.
• GET /offers/{id} returns remaining_time, the seconds left before expiry.
• Offers don't hold the unit. The hotel's inventory isn't reserved until you book. In practice, if you book within about 10 minutes of searching, the price rarely changes, but refresh before booking to be sure.

When an offer is not found

The offer endpoints return 404 (and a booking is rejected with offer … does not exist) when the offer no longer exists for your account:

• It expired. Offers are kept for 1 hour after the search or the last refresh / live-check.
• It was already booked. Once a booking request with the offer is accepted, the offer is removed, whatever the outcome at the hotel.
• The ID is wrong.

In every case, run a new availability search.

Retrieve, live-check, refresh

Recommendation: just before you submit the booking, call POST /offers/{id}/refresh.

• 202: book.
• Error: act on the code; see Offer errors.

What happens at booking time

When you POST /bookings, we may check the offer with the hotel again. If it can't be booked as it is, the booking is rejected with one of the codes in Offer errors. To avoid this, refresh the offer just before booking.

The hotel can still reject the booking at a different price after it was accepted. In that case the reservation ends up FAILED with error code PRICE_CHANGED (Booking).

Using one offer for several units

• One offer ID can be used for as many reservations (units) in a single booking as number_of_units[property_id][unit_id] allows in the availability response.

• Going over that limit gives:

  Offer `<id>` can be used 1 times, found 2 usages

• After a refresh or live-check, the number of available units may have dropped. Search again if you need more units than the offer now allows.

• In multi-unit searches, also respect occupancy_has_offer; see Availability.

• Sending more reservations than units in your search's occupancy gives offer … has been sent more times than occupancy list size. Send one reservation per searched unit.

Offers are single-use

Once a booking request has been made with an offer, don't reuse that offer ID, even if the booking failed or timed out. Run a new availability search to get a fresh offer.

• A new search can return the same offer ID again if the same unit, rate, dates and occupancy are still available. That's expected: it is bookable again.
• If you retry a booking after your request timed out and get offer … is not valid or … is not available, the first request most likely went through. Check with support before booking the guest again.

Offer errors

🚧

Coming soon

These codes aren't returned yet. Until then, the offer endpoints return 404 (Offer … was not found or has already expired) and bookings are rejected with offer … has expired. Please refresh the offer before submitting a booking. In both cases, live-check the offer to see the current price, or search again.

POST /offers/{id}/refresh, GET /offers/{id}?live_check=true and the offer checks in POST /bookings return one of these codes in error_codes[].code: