Limits
Hard limits on rooms, guests, stay length and search size, the field rules the API validates, the clocks that run during a booking flow, and what the API does not support.
At a glance
Validate these in your own UI before you call the API. A search that breaks a limit costs the guest a round trip and gives them nothing to fix. Some limits are not checked when the request arrives, so a request that breaks them isn't rejected up front; the table says which.
Booking and search limits
| Limit | Value | |
|---|---|---|
| Rooms per booking | 1 to 4. Each distributions[] entry is one room, and rooms can have different occupancy. 0 or 5 rooms is rejected with 400. | |
| Guests per room | 1 to 6, children included. A seventh person is rejected with 400, whatever the mix of adults and children. | |
| Adults and children per room | At least 1 adult and at most 5 children. Not checked when the request arrives: a room with no adult gets through, so check it yourself. | |
| Guests per booking | 15, with at most 14 children. | |
| Child ages | 0-17 inclusive. Send the age at checkout. | |
| Length of stay | 30 nights at most, counted as checkOut minus checkIn (1 to 31 March is 30 nights). A longer stay is rejected with 400, You cannot select more than 30 nights. The check runs before any supplier is asked, and suppliers may add their own restrictions. | |
| Hotel codes per Quote | 3,000. 3,001 is rejected with 400. | |
| Search radius | All the codes in one Quote within about 200 km of each other. | |
| Datasheets per call | 100 ids per GET /accommodations/datasheet. | |
| Accommodation list page | limit of 20,000 per GET /accommodations page. | |
| Currency | The microsite currency only. You cannot request another one. | |
| Price-change tolerance | Set per microsite, as a percentage or a fixed amount. Default 0.5%. |
A Book whose closing price moves beyond the tolerance still books, but closes PRICE_ERROR. See Booking statuses.
Field limits
The OpenAPI spec defines these rules. The ones marked Tested are enforced when the request arrives: a request that breaks them gets 400 naming the field (see Errors). Check all of them client-side so the guest can fix their input before Prebook.
| Field | Call | Rule | |
|---|---|---|---|
externalReference | Book | String, at most 50 characters. | |
timeout | Quote, Quote single | Integer in milliseconds, at least 3000: 2999 is rejected. Send null or leave it out to use your account's default. | |
filter.maxCombinations | Quote | 1 to 60: 61 is rejected. Defaults to 1 when bestCombinations is true and 60 when it is false. | |
accommodations | Quote | Unique codes, at most 3,000. Deduplicate before sending. Use it or destinationId, not both: sending both, or neither, is not rejected up front, and what the search does then is untested. | |
name, lastName | Prebook | Latin script only: ^[\p{IsLatin} .'-]+$. Transliterate other scripts first. | |
phone | Prebook | Digits only, at most 15. | |
phoneCountryCode | Prebook | + followed by digits, 2 to 4 characters in total, for example +34 or +966. 0034 is rejected. | |
documentNumber | Prebook | Letters and digits with at most two -, at most 20 characters. | |
email | Prebook | Email format. | |
requestedAge | Prebook | Always mandatory, even when requiredField doesn't list it. | |
Fields in requiredField | Prebook | Every field Confirm lists for a person must be sent, or Prebook returns 400 with one message per missing field, for example Missing the following required field of the contact person: Birthdate. |
The errors the API returns when passenger data fails are listed in the FAQ.
Time limits
- Every response restarts the key clock. When a key or the token expires, start again from Quote with a fresh token.
- The whole flow must run on one token, so only start a flow when the token has at least 60 minutes left. See Authentication.
- Don't cache quoted prices in your catalogue. Rates are valid for about an hour, and keys expire 40 to 60 minutes after the response that issued them.
Calls can take a while: the docs examples show a Quote taking 18 seconds, Book 11 seconds and Cancel 9 seconds. Set your HTTP timeout for quotes to at least the request's timeout plus 30 seconds, and to at least 120 seconds for Book and Cancel.
Not supported
| Feature | What the API does instead | |
|---|---|---|
| Push rates | Not available. Pull availability and prices with Quote. | |
| Bedding type | Cannot be sent to the hotel. | |
| Structured special requests | Not supported. Send free text in commentToAccommodation at Prebook. | |
| Per-room guest names to suppliers | The API accepts them, but only mandatory data is forwarded to suppliers. | |
| Multi-currency or a currency per request | Prices come in the microsite currency. Convert for display yourself. | |
| Several hotels in one booking flow | One flow books one hotel. To search many hotels, send a list of codes to Quote. | |
| XML | JSON only. |
Related
Hotel catalogue
Build and sync a local copy of the hotel catalogue for hotel pages, maps, filters, autocomplete and SEO. Prices never come from the catalogue, only from Quote.
Pitfalls
Where the spec and the docs disagree, and the mistakes that break hotel integrations most often, from the booking flow to reading bookings in production. Each one comes with what to do instead.