Hotel API conventions

Identifiers and response envelopes

You receive hotel listings as htl_ IDs, bookings as bkg_ IDs and saved place resolutions as plc_ IDs. Treat the entire value as opaque. Supply the service's hotel IDs to offers and content. For offers 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. Your reference_id is an optional business reference, not an idempotency key.

You read successful business results from data. Collection and offer responses can include meta with pagination or the selected supplier. Your prebook response can also contain a one-time Payment SDK token in meta.

Contract evolution

You send only documented request fields; request bodies are closed, and unknown booking-list filters are rejected with HTTP 400. Response schemas are open because later releases can add fields: tolerate a field you do not recognize rather than rejecting the response. The published schemas describe the current response shape, including its required fields. Continue to validate the fields your integration uses, and treat an unknown status or enum value as unsupported rather than assuming success.

You receive updated reference and integration guidance with field removals, new required request fields, type changes and changed business meanings; do not infer compatibility from the /v1 prefix alone.

Money and terms

You receive monetary amounts in major currency units with an uppercase currency code; an amount of 125.50 USD means 125 dollars and 50 cents. Do not compare different currencies as if they were interchangeable.

You use the booking total for the complete stay. Room totals and room cancellation terms apply only to their room when supplied. Some suppliers provide only a booking-level total or policy; missing room values do not mean the room is free, and you must not count a booking-level price or policy once per room.

You display due_at_property separately from the booking total. It is one amount when a complete total is known, a list when complete room charges use different currencies, or null when the total is unknown. Null fees, policies and refunds remain unknown; do not display them as zero or free cancellation.

Dates and occupancy

You send check_in and check_out as calendar dates in YYYY-MM-DD form. Your stay is at most 99 nights. Expiry and cancellation boundary timestamps identify instants; preserve their offsets and use any supplied policy time zone when explaining a deadline.

You send one occupancy per room, with at least one adult and each child's age from 0 to 17. The request schema permits up to eight rooms, but supplier limits can be lower. WebBeds supports up to five rooms and child ages up to 12. Your guest names at prebook must match the priced room assignment, with one adult lead per room.

You receive one rooms entry per occupancy on each offer, ordered by its zero-based position. Its adults and children describe that requested room, and optional room_type, board and room_photos describe the offered room. Each room has at most one preview photo; missing descriptive fields mean the supplier or cached content provides none. Your offer's top-level room_type and board remain first-room summaries for single-room summaries. Use the per-room fields for a multiroom selection, and never treat missing room cancellation terms as free cancellation.

Pagination and limits

You page search results with limit (default 10, maximum 100) and cursor. Search returns meta.pagination with limit and next_cursor, without a total count. Send next_cursor as cursor with the same search fields to read the next page, because it keeps your later pages on the supplier that answered the first; stop when it is omitted, because a page can come back short or empty before the end. It expires after 30 minutes. You page your bookings with limit (default 25, maximum 100) and offset (default 0, capped at 100000); booking meta contains limit, offset and has_more. When has_more is true, add limit to offset and retain your filters; stop when it is false. If your next offset would exceed the cap, narrow your status or reference_id filters. Concurrent changes can shift an offset-based page, so this is not a snapshot or an export of your complete history.

You receive bookings newest first, with booking ID breaking creation-time ties. You can filter by status and your exact reference_id; you cannot change the sort order through this endpoint.

You price up to 10 hotel IDs from one supplier per offers request; split a longer search page across several requests. You request at most 250 offers in total, hotel IDs times max_offers_per_hotel, so each response stays within its size limit. Hotels without available offers can be omitted. You keep each JSON request body within 1 MiB.

Places and content

You can resolve a destination with GET /places?query=Dubai. You receive the best match and alternatives, rather than a hotel list. Pass location.latitude, location.longitude and suggested_radius into the geographic destination fields of your search. Your place ID cannot be used as a hotel ID.

You can search LiteAPI by city or coordinates. WebBeds requires a supported city and country; Duffel requires geographic coordinates and a radius. Resolve your destination first when you need coordinates.

You receive radii in metres: place suggestions cover 1000–50000 metres, and geographic search accepts 1000–100000 metres. A suggested radius can omit parts of a large region, so inspect the resolved location.

You use content for descriptive information. Cached content can be returned while details or reviews refresh independently. Your response contains at most twenty images and twenty reviews, with reviewer names omitted. Availability and pricing still come from search and offers.