Hotel booking flow

You search with one occupancy for each room, including every child's age. Keep the room order when you prebook, because guest assignments bind to that order.

Search and select

You use the returned hotel IDs with offers and content. You can instead send each hotel's supplier_hotel_id in supplier_hotel_ids, with meta.supplier as supplier, but not both kinds of ID in one request. A search price is for comparison. Request offers for your selected hotels to obtain an offer reference for the complete stay.

You review every entry in the offer's rooms before choosing it. Each position matches your original occupancy order; rooms can have different types, board and cancellation terms. The offer's total prices all rooms together. A policy inside a room applies only to that room; a policy on the offer applies to the whole stay and is counted once. Duffel supplies whole-offer cancellation terms, so its room entries omit individual policies.

You pass the offer reference unchanged to prebook before its expiry. It binds your organization, room party, dates, source market and price. A new stay or party requires a new offer.

Assign guests and prebook

You provide one adult lead per room. You can name additional guests up to the priced occupancy. For WebBeds, you name every adult and supply each named guest's type; the supplier requires those details before payment. Use an international contact phone number for Duffel.

You send a stable idempotency key for one prebook operation. Repeating that key as the same organization and user returns its stored booking, even if the original offer has since expired. Use a new key only for a new intended booking.

You review the prebook total and terms before completing payment. Amounts in responses use major currency units. The total covers the whole booking; property charges are separate. Missing cancellation terms or fees mean unknown, not zero.

Pay and book

You choose one payment path. For a saved instrument, send payment_instrument_id when booking. For the payment SDK, set use_payment_sdk at prebook, use the returned token, and omit payment_instrument_id when booking. The token is returned once and is not available on a later booking read.

You complete the same booking after authorization. A confirmed booking remains confirmed if payment capture needs recovery. If the purchase result is unknown, read that booking and contact support with its request ID; creating another booking may reserve the stay twice.

You read bookings using the same organization and owner identity that created them. Through the API gateway, that owner is the API-key ID, not an individual traveler. Another key in the same organization does not inherit booking access. Creating a replacement key creates a new owner identity; contact support to establish booking access continuity before retiring the original key. A booking belonging to another owner returns not found.

Show how your traveller paid

You read every payment on the booking in payments, oldest first, so a declined attempt can come before the payment that succeeded. Each payment carries its status, its amount and, when known, the card: its brand, last four digits, funding and any wallet.

You treat a payment's status as the last outcome recorded for it, not a live reading, because it can trail the money: a capture can go through while recording it fails, which leaves the payment AUTHORIZED although the booking is confirmed. FAILED does not always mean the card's bank declined it; a card that asks for an authentication step that is not supported also fails.

You can receive a payment without its card. A payment that is still INITIATED has no card yet, and one the provider holds no card for, such as a payment refused before the provider recorded it, has no card to display. The card is read from the payment provider each time you read the booking, so one that could not be read in time is left out: read the booking by ID again later for it. The booking list never carries cards.

You find bookings by the reference you supplied at prebook with GET /bookings?reference_id=YOUR_REFERENCE, URL-encoding the reference. Matching is exact and case-sensitive after surrounding whitespace is trimmed. You can also filter by one status, such as CONFIRMED, and combine both filters. References are not unique: read every matching page and use each booking's ID for subsequent operations. The list is scoped to the same organization and user as the original booking; these filters do not grant access to another user's bookings. Keep the filters unchanged while paging and stop when meta.has_more is false.