Check price
POST/v2.0/orders/checkPrice
Introduction
Re-checks a cart of items live, right before booking, and returns one bookingToken
covering everything that is still bookable. Suppliers are queried live (not from cache), so
this call is slower than a search and is meant to be used right before booking.
Items and rooms
Each item has a type, the product it is, which picks the item's schema. Only hotel for
now: one hotel reservation group, rooms in one hotel for one stay. Each room names
the rate it wants with a rateToken from a search; identical rooms may reuse the same token.
Rooms of an item may have different occupancies. Items may differ in hotel and dates.
Statuses
Every room and item gets a status: AVAILABLE, PRICE_CHANGED (still bookable, at the new
price) or UNAVAILABLE. An item is unavailable as soon as one of its rooms is, since it is
booked as a whole. The call itself only fails (4xx) when the request is invalid.
Each room becomes its own reservation.
Request
- application/json
Body
- 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.
items object[]required
The cart, 1 to 5 items. Each item's type says which product it is and picks the item's schema. Only hotel for now: one item per hotel reservation group.
Possible values: [hotel]
Product type: hotel.
Client name for the item, unique in the request: 1 to 20 characters [A-Za-z0-9_-].
rooms object[]required
The item's rooms, 1 to 8. They must share the hotel and the dates; occupancies may differ.
Client name for the room, unique in the item — usually the rooms[].ref used in the search.
The rate wanted for this room, from a search (hotels[].rooms[].rates[].rateToken). The same token may be used by several identical rooms.
Language for the texts: pt-BR, en-US or es-ES. Defaults to the language of the search the tokens came from.
When true, each item also lists the payment options every one of its rooms accepts, and an item whose rooms share none is UNAVAILABLE (NO_COMMON_PAYMENT_OPTION). Default false.
Responses
- 200
- default
- application/json
- Schema
- Example (from schema)
Schema
- Array [
- Array [
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- 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.
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, as sent.
Possible values: [AVAILABLE, PRICE_CHANGED, UNAVAILABLE]
UNAVAILABLE if any room is, or if the rooms share no payment option while commonPaymentOptions is on — an item is booked as a whole. Otherwise PRICE_CHANGED if any room's price changed, else AVAILABLE.
rooms object[]required
The item's rooms, in the order sent.
The room's ref, as sent.
Possible values: [AVAILABLE, PRICE_CHANGED, UNAVAILABLE]
PRICE_CHANGED: still bookable, but the total differs from the search (see previousTotal). UNAVAILABLE: see error.
The input rateToken, echoed.
roomType objectnullable
Room type ID.
Room type name.
Room description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.
Rooms of this rate still available, when the supplier says.
price objectnullable
Currency of every amount in this price (ISO 4217), except payAtProperty.
Price before taxes, when available.
Tax amount, when available.
Total value (base + taxes), when available.
Total discount on the rate. Informative: base and total already have it taken off. Absent when there is none.
commission objectnullable
What the client earns on this rate. Absent on rates without commission.
Commission amount, in the price's currency.
Commission rate, in percent (10.00 is 10%).
payAtProperty object[]nullable
Fees the guest pays at the hotel, each in the currency the hotel charges. Never included in total. Only returned by v2.0/orders/checkPrice. Absent when there is none.
What the fee is, as the supplier names it.
Monetary amount.
Currency the hotel charges the fee in (ISO 4217).
breakdown objectnullable
How the price splits up. See PriceBreakdown for when it is returned.
nights object[]nullable
Price of each night, in stay order. The nights' base add up to the rate's base. Absent when the supplier doesn't price each night.
Date of the night (YYYY-MM-DD).
Price of the night before taxes, in the price's currency.
taxes object[]nullable
The taxes in taxes, as the supplier details them. Informative. Absent when not detailed.
What the amount is, as the supplier names it.
Monetary amount, in the price's currency.
discounts object[]nullable
The discounts in discounts, as detailed. Informative. Absent when not detailed.
What the amount is, as the supplier names it.
Monetary amount, in the price's currency.
previousTotal objectnullable
Monetary amount.
Currency code (ISO 4217).
cancelPolicy objectnullable
Whether cancelling can be free at some point. false for non-refundable rates. Absent when unknown.
Currency of the penalty amounts (ISO 4217). Absent when no step has an amount.
penalties object[]nullable
Penalty steps in time order. Before the first step, cancelling is free. Absent when the supplier gives no penalty information.
When this step starts (ISO 8601 with UTC offset). Absent means from the moment of booking, as for non-refundable rates.
What cancelling costs from then on, for this room and the whole stay, in the policy's currency. Absent when the supplier doesn't say.
Cancellation policy as the supplier words it. Only returned by v2.0/orders/checkPrice, not by the search.
supplier objectnullable
Name of the supplier providing this rate.
URL of the supplier's logo. Absent when the credential has none on file.
offers object[]nullable
Promotional offers applied to the rate.
Offer name.
Discount value/percentage.
Number of free nights granted by the offer, when applicable.
Possible values: [STAY_DISCOUNT, DISCOUNT, FREE_NIGHT, LAST_MINUTE, null]
Discount type.
Nights required to qualify for the offer, when applicable.
paymentOptions object[]nullable
Payment/guarantee options accepted for this room.
Payment option ID: pass it as is to v2.0/orders/booking (payments[].paymentOptionId). Opaque: don't parse it.
Possible values: [CREDITCARD, PAY_AT_PROPERTY, INVOICE, PAY_LATER]
CREDITCARD: paid by credit card. PAY_AT_PROPERTY: paid at the hotel, with a card as guarantee. INVOICE: billed to the client account. PAY_LATER: paid after booking, before a deadline. More types may be added: accept values you don't know.
Display name for the payment option.
Human-readable description.
card objectnullable
Accepted card brands, e.g. VISA, MASTERCARD. Absent when any brand is accepted.
payLater objectnullable
When the booking is cancelled automatically if not paid, ISO 8601 UTC. Absent when the supplier gives none.
mealPlan objectnullable
Possible values: [breakfast, lunch, dinner]
Meals included in the rate. An empty list means room only.
true when the rate is all-inclusive: every meal and usually drinks and more. Absent otherwise.
Meal plan name, as the supplier gives it.
Meal plan description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.
ratePlan objectnullable
Rate plan ID.
Rate plan name.
Whether the rate plan is publicly published.
Whether the rate plan is a package (bundled with extras).
Rate plan description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.
Promotional code the supplier applied to this rate (Omnibees PromotionCode), kept on the booking. Absent when no code applies.
remarks object[]nullable
The supplier's notes about the hotel and this rate: house rules (check-in and check-out times, children, pets…), rate comments, fees paid at the hotel, warnings. They often hold things the guest must be told before booking, so show them. Only returned here, not by the search. Absent when the supplier gives none.
Remark title, e.g. General Policies, Pets or Warning. Absent when the supplier gives none.
Remark text.
error objectnullable
Stable code: SOLD_OUT, NOT_ENOUGH_UNITS (room) or NO_COMMON_PAYMENT_OPTION (item).
Human-readable explanation.
hotel objectnullable
Internal Niara ID of the hotel.
Hotel name.
Name of the hotel's city.
Name of the hotel's country.
Hotel address.
position objectnullable
Geographic coordinates of the hotel.
Latitude of the hotel.
Longitude of the hotel.
URL of the hotel's main image.
URL with the hotel's full descriptive content.
Hotel star rating, when known.
Whether this is one of the client's preferred hotels.
total objectnullable
Monetary amount.
Currency code (ISO 4217).
previousTotal objectnullable
Monetary amount.
Currency code (ISO 4217).
paymentOptions object[]nullable
Payment options every room of the item accepts. Only when commonPaymentOptions is on.
Payment option ID: pass it as is to v2.0/orders/booking (payments[].paymentOptionId). Opaque: don't parse it.
Possible values: [CREDITCARD, PAY_AT_PROPERTY, INVOICE, PAY_LATER]
CREDITCARD: paid by credit card. PAY_AT_PROPERTY: paid at the hotel, with a card as guarantee. INVOICE: billed to the client account. PAY_LATER: paid after booking, before a deadline. More types may be added: accept values you don't know.
Display name for the payment option.
Human-readable description.
card objectnullable
Accepted card brands, e.g. VISA, MASTERCARD. Absent when any brand is accepted.
payLater objectnullable
When the booking is cancelled automatically if not paid, ISO 8601 UTC. Absent when the supplier gives none.
mandatoryFields objectnullable
buyer object
Required on buyer.
Required inside person, when the party is sent as a person.
Required inside company, when the party is sent as a company. vatNumber and corporateName are always required on top.
Required on each room's primary guest (rooms[].guests[].primary: true).
Required on every other adult of each room. Empty unless the checkout form asks for every guest.
Required instead of secondaryGuests, for a guest with type: CHILD. Empty unless the checkout form asks for every guest or for children.
Required instead of whichever of the above would otherwise apply, for a guest whose address.country isn't BR.
payer object
Required on a payment's payer (payments[].payer). Empty unless the checkout form asks for a separate payer. A payment without a payer bills the buyer, which isn't checked again.
Required inside person, when the party is sent as a person.
Required inside company, when the party is sent as a company. vatNumber and corporateName are always required on top.
error objectnullable
Stable code: SOLD_OUT, NOT_ENOUGH_UNITS (room) or NO_COMMON_PAYMENT_OPTION (item).
Human-readable explanation.
totals object[]
Sum of the bookable items' totals, one entry per currency.
Monetary amount.
Currency code (ISO 4217).
One token covering every item that is not UNAVAILABLE, with all its rooms. Pass it to v2.0/orders/booking; all of them must be booked together, in that one call. Absent when nothing is bookable.
When bookingToken expires (15 minutes after the price check), ISO 8601 UTC.
The language actually used for the texts.
{
"requestId": "string",
"externalRequestId": "string",
"timestamp": "string",
"items": [
{
"ref": "string",
"rooms": [
{
"ref": "string",
"rateToken": "string",
"roomType": {
"id": "string",
"name": "string",
"description": "string"
},
"unitsAvailable": 0,
"price": {
"currency": "string",
"base": "string",
"taxes": "string",
"total": "string",
"discounts": "string",
"commission": {
"amount": "string",
"percentage": "string"
},
"payAtProperty": [
{
"description": "string",
"amount": "string",
"currency": "string"
}
],
"breakdown": {
"nights": [
{
"date": "string",
"base": "string"
}
],
"taxes": [
{
"description": "string",
"amount": "string"
}
],
"discounts": [
{
"description": "string",
"amount": "string"
}
]
}
},
"previousTotal": {
"amount": "string",
"currency": "string"
},
"cancelPolicy": {
"refundable": true,
"currency": "string",
"penalties": [
{
"from": "string",
"amount": "string"
}
],
"description": "string"
},
"supplier": {
"name": "string",
"logo": "string",
"offers": [
{
"name": "string",
"discount": 0,
"freeNights": 0,
"nightsRequired": 0
}
]
},
"paymentOptions": [
{
"id": "string",
"name": "string",
"description": "string",
"card": {
"brands": [
"string"
]
},
"payLater": {
"deadline": "string"
}
}
],
"mealPlan": {
"meals": [
null
],
"allInclusive": true,
"name": "string",
"description": "string"
},
"ratePlan": {
"id": "string",
"name": "string",
"public": true,
"package": true,
"description": "string"
},
"promoCode": "string",
"remarks": [
{
"name": "string",
"description": "string"
}
],
"error": {
"code": "string",
"message": "string"
}
}
],
"hotel": {
"id": "string",
"name": "string",
"cityName": "string",
"countryName": "string",
"address": "string",
"position": {
"latitude": 0,
"longitude": 0
},
"imageUrl": "string",
"detailsUrl": "string",
"rating": 0,
"preferred": false
},
"total": {
"amount": "string",
"currency": "string"
},
"previousTotal": {
"amount": "string",
"currency": "string"
},
"paymentOptions": [
{
"id": "string",
"name": "string",
"description": "string",
"card": {
"brands": [
"string"
]
},
"payLater": {
"deadline": "string"
}
}
],
"mandatoryFields": {
"buyer": {
"person": [
"string"
],
"company": [
"string"
]
},
"primaryGuest": [
"string"
],
"secondaryGuests": [
"string"
],
"children": [
"string"
],
"foreign": [
"string"
],
"payer": {
"person": [
"string"
],
"company": [
"string"
]
}
},
"error": {
"code": "string",
"message": "string"
}
}
],
"totals": [
{
"amount": "string",
"currency": "string"
}
],
"bookingToken": "string",
"expiresAt": "string",
"language": "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"
}
]
}
}