Booking
POST/v2.0/orders/booking
Introduction
Books every item and room of a price check (v2.0/orders/checkPrice), using its bookingToken. Each room
becomes its own reservation in the same order. Booking is asynchronous: this call only
confirms the request was accepted for processing, not that the reservations are confirmed
yet — see status on the response.
Retries and duplicates
externalReference is your ID for the order, and it is what protects a booking from being made
twice. A reference can have only one order: booking again with a reference that already has one
returns 409 DUPLICATE_REFERENCE, whatever the rest of the request, including when that order was
later cancelled. The only exception is an order that wasn't booked: FAILED or PRICE_CHANGED on
the response, FAILED on v2.0/orders/details. The same reference can then be booked again.
So after a timeout or a network error, send the same request again. A 409 DUPLICATE_REFERENCE
means the first attempt went through: read the order with v2.0/orders/details by
externalReference. It may take a few seconds to show up there.
Request
- application/json
Body
- Array [
- Array [
- Array [
- ]
- ]
- ]
- Array [
- Array [
- ]
- ]
Your id for this call, up to 128 printable characters. Returned as is in the response, success or error, and kept in our logs: quote it when contacting support, even if the response never reached you. Use a new value for each call.
When you sent this request, by your clock: ISO 8601 with a timezone offset, e.g. 2026-11-13T14:32:05.120-03:00. Kept in our logs.
The token from v2.0/orders/checkPrice (bookingToken). items must cover every item and room it holds, each exactly once: everything in the price check is booked together, in this one call.
items object[]required
The items from the price check to book. Each item's type says which product it is and picks the item's schema. Only hotel for now: its rooms, with their guests.
Possible values: [hotel]
Product type: hotel. Must match the item's type in the price check.
The item's ref, as sent to (and returned by) v2.0/orders/checkPrice.
expectedTotal objectrequired
Monetary amount.
Currency code (ISO 4217).
rooms object[]required
Every room of the item from the price check, each exactly once.
The room's ref, as sent to (and returned by) v2.0/orders/checkPrice.
guests object[]required
One entry per guest staying in the room. The count of ADULT/CHILD guests must match the room's occupancy, and when every child has age, the ages must match the searched childrenAges.
Guest's first name.
Date of birth (ISO 8601).
ISO 3166-1 alpha-2.
address objectnullable
State or province, e.g. SP.
Postal code.
The address country, ISO 3166-1 alpha-2.
documents objectnullable
Brazilian CPF. Punctuation is accepted; check digits are validated.
rg objectnullable
Issuing organ, e.g. SSP-SP. Only with number.
passport objectnullable
Birth certificate number. Only kept for guests.
other objectnullable
Document type, e.g. CO_CC.
Possible values: [ADULT, CHILD]
Age category of the guest.
Whether this is the room's primary guest. Must be ADULT; exactly one per room.
Free-text special requests for this room, sent to the hotel after the item's comments.
Free-text comments for the hotel (e.g. late check-in), sent with every room of the item.
buyer objectrequired
person objectnullable
Date of birth (ISO 8601).
ISO 3166-1 alpha-2.
address objectnullable
State or province, e.g. SP.
Postal code.
The address country, ISO 3166-1 alpha-2.
documents objectnullable
Brazilian CPF. Punctuation is accepted; check digits are validated.
rg objectnullable
Issuing organ, e.g. SSP-SP. Only with number.
passport objectnullable
Birth certificate number. Only kept for guests.
other objectnullable
Document type, e.g. CO_CC.
company objectnullable
Tax ID. For a Brazilian company (address.country absent or BR), the CNPJ, numeric or alphanumeric; punctuation is accepted, check digits are validated. For a company outside Brazil, its tax ID as issued in its country, sent as is.
Legal name ("razão social").
Trade name ("nome fantasia").
Brazilian state tax registration ("inscrição estadual").
Brazilian municipal tax registration ("inscrição municipal").
address objectnullable
State or province, e.g. SP.
Postal code.
The address country, ISO 3166-1 alpha-2.
payments object[]required
Payment(s) to charge for this purchase. Exactly one is currently supported; multiple payments aren't accepted yet.
The payment option being charged, as returned by v2.0/orders/checkPrice (items[].rooms[].paymentOptions[].id). It must be accepted by every room of every item this payment covers.
card objectnullable
Card brand, e.g. VISA. Must be one of the option's card.brands, when it lists any.
Cardholder name, as on the card.
Expiry as MMYY, e.g. 1230.
Default value: 1
Number of installments. Only 1 is currently accepted: interest-bearing installment handling isn't supported yet.
paidItems object[]
Which item(s) this payment covers, and how much of each. Optional: without it, this payment covers the whole booking, in full.
The item (items[].ref) this portion of the payment applies to.
Portion of that item's total covered by this payment. Split across the item's rooms by room price.
payer objectnullable
person objectnullable
Date of birth (ISO 8601).
ISO 3166-1 alpha-2.
address objectnullable
State or province, e.g. SP.
Postal code.
The address country, ISO 3166-1 alpha-2.
documents objectnullable
Brazilian CPF. Punctuation is accepted; check digits are validated.
rg objectnullable
Issuing organ, e.g. SSP-SP. Only with number.
passport objectnullable
Birth certificate number. Only kept for guests.
other objectnullable
Document type, e.g. CO_CC.
company objectnullable
Tax ID. For a Brazilian company (address.country absent or BR), the CNPJ, numeric or alphanumeric; punctuation is accepted, check digits are validated. For a company outside Brazil, its tax ID as issued in its country, sent as is.
Legal name ("razão social").
Trade name ("nome fantasia").
Brazilian state tax registration ("inscrição estadual").
Brazilian municipal tax registration ("inscrição municipal").
address objectnullable
State or province, e.g. SP.
Postal code.
The address country, ISO 3166-1 alpha-2.
Your own ID for this order, up to 64 characters; spaces around it are dropped. Unique among your orders: a reference that already has an order gets 409 DUPLICATE_REFERENCE, so retrying after a timeout never books twice. It can be booked again only after its order failed. The order can be read by it on v2.0/orders/details.
Language for the texts: pt-BR, en-US or es-ES. Defaults to the language of the price check.
Responses
- 200
- default
- application/json
- Schema
- Example (from schema)
Schema
- Array [
- Array [
- ]
- ]
- Array [
- ]
Our id for this call, also in the X-Request-Id header. Quote it when contacting support.
The externalRequestId of the request, as sent. Absent when it wasn't sent.
When we answered, by our clock: ISO 8601 in UTC, e.g. 2026-11-13T17:32:05.874Z.
Your externalReference for the order, as sent.
Possible values: [INPROGRESS, FAILED, PRICE_CHANGED]
PRICE_CHANGED means the price of at least one room moved since the price check; see priceChanges. Nothing was booked or charged, for any room: check the price again and book with the same externalReference. Confirming the new price in this order isn't supported yet.
items object[]required
The items, in the order sent. Each has the schema of its type.
Possible values: [hotel]
Product type: hotel.
The item's ref.
rooms object[]required
The item's rooms, in the order sent.
The room's ref.
ID of the reservation created for this room. Absent when the room was not accepted for processing.
priceChanges object[]nullable
Populated only when status is PRICE_CHANGED.
ID of the reservation whose price changed.
The item the room belongs to.
The room whose price changed.
The total price this room was booked at.
The room's current, live total price.
{
"requestId": "string",
"externalRequestId": "string",
"timestamp": "string",
"orderId": "string",
"externalReference": "string",
"items": [
{
"ref": "string",
"rooms": [
{
"ref": "string",
"reservationId": "string"
}
]
}
],
"priceChanges": [
{
"id": "string",
"itemRef": "string",
"roomRef": "string",
"referenceTotal": "string",
"supplierTotal": "string",
"difference": "string",
"currency": "string"
}
]
}
Error. The status depends on error.code.
- application/json
- Schema
- Example (from schema)
Schema
- Array [
- ]
Our id for this call, also in the X-Request-Id header. Quote it when contacting support.
The externalRequestId of the request, as sent. Absent when it wasn't sent.
When we answered, by our clock: ISO 8601 in UTC, e.g. 2026-11-13T17:32:05.874Z.
error objectrequired
Stable reason; decide what to do based on it, not on message.
| Code | Status | When |
| --- | --- | --- |
| INVALID_REQUEST | 400 | The request was rejected; field problems are listed in details |
| UNAUTHORIZED | 401 | Missing or invalid credentials |
| FORBIDDEN | 403 | Valid credentials, access denied |
| NOT_FOUND | 404 | Order not found, or no endpoint for this method and path |
| TOKEN_EXPIRED | 409 | rateToken or bookingToken past its expiration; search or check the price again |
| DUPLICATE_REFERENCE | 409 | The booking's externalReference already has an order; read it with v2.0/orders/details |
| FEATURE_NOT_AVAILABLE | 422 | A valid request that isn't supported yet |
| RATE_LIMITED | 429 | Too many requests, or quota exceeded |
| SEARCH_FAILED | as received | The hotel search failed; message has the reason given |
| BOOKING_FAILED | as received | The booking was not completed; message has the reason given |
| CANCELLATION_FAILED | as received | The cancellation was not completed; message has the reason given |
| SUPPLIER_ERROR | 502 | A supplier failed or answered badly |
| TIMEOUT | 504 | The request took too long; a booking may still complete |
| INTERNAL_ERROR | 500 | Unexpected failure on our side |
Explanation for people. May change; don't parse it.
details object[]nullable
Every field problem found, even when there is only one. Only with INVALID_REQUEST.
INVALID_FIELD (a value is wrong) or REQUIRED_FIELD (a value is missing).
Path of the field in the request, e.g. items[0].rooms[1].rateToken. Absent when the problem involves several fields.
Explanation, in English.
{
"requestId": "string",
"externalRequestId": "string",
"timestamp": "string",
"error": {
"code": "string",
"message": "string",
"details": [
{
"code": "string",
"field": "string",
"message": "string"
}
]
}
}