Skip to main content

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​

Body

    externalRequestId stringnullable

    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.

    timestamp stringnullable

    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.

  • Array [
  • type required

    Possible values: [hotel]

    Product type: hotel.

    ref stringrequired

    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.

  • Array [
  • ref stringrequired

    Client name for the room, unique in the item — usually the rooms[].ref used in the search.

    rateToken stringrequired

    The rate wanted for this room, from a search (hotels[].rooms[].rates[].rateToken). The same token may be used by several identical rooms.

  • ]
  • ]
  • language stringnullable

    Language for the texts: pt-BR, en-US or es-ES. Defaults to the language of the search the tokens came from.

    commonPaymentOptions booleannullable

    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​

Schema
    requestId stringnullable

    Our id for this call, also in the X-Request-Id header. Quote it when contacting support.

    externalRequestId stringnullable

    The externalRequestId of the request, as sent. Absent when it wasn't sent.

    timestamp stringnullable

    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.

  • Array [
  • type required

    Possible values: [hotel]

    Product type: hotel.

    ref stringrequired

    The item's ref, as sent.

    status required

    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.

  • Array [
  • ref stringrequired

    The room's ref, as sent.

    status required

    Possible values: [AVAILABLE, PRICE_CHANGED, UNAVAILABLE]

    PRICE_CHANGED: still bookable, but the total differs from the search (see previousTotal). UNAVAILABLE: see error.

    rateToken stringrequired

    The input rateToken, echoed.

    roomType objectnullable
    id stringrequired

    Room type ID.

    name stringrequired

    Room type name.

    description stringnullable

    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.

    unitsAvailable integernullable

    Rooms of this rate still available, when the supplier says.

    price objectnullable
    currency stringnullable

    Currency of every amount in this price (ISO 4217), except payAtProperty.

    base decimalnullable

    Price before taxes, when available.

    taxes decimalnullable

    Tax amount, when available.

    total decimalnullable

    Total value (base + taxes), when available.

    discounts decimalnullable

    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.

    amount decimalrequired

    Commission amount, in the price's currency.

    percentage decimalnullable

    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.

  • Array [
  • description stringnullable

    What the fee is, as the supplier names it.

    amount decimalrequired

    Monetary amount.

    currency stringrequired

    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.

  • Array [
  • date stringrequired

    Date of the night (YYYY-MM-DD).

    base decimalrequired

    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.

  • Array [
  • description stringnullable

    What the amount is, as the supplier names it.

    amount decimalrequired

    Monetary amount, in the price's currency.

  • ]
  • discounts object[]nullable

    The discounts in discounts, as detailed. Informative. Absent when not detailed.

  • Array [
  • description stringnullable

    What the amount is, as the supplier names it.

    amount decimalrequired

    Monetary amount, in the price's currency.

  • ]
  • previousTotal objectnullable
    amount decimalrequired

    Monetary amount.

    currency stringrequired

    Currency code (ISO 4217).

    cancelPolicy objectnullable
    refundable booleannullable

    Whether cancelling can be free at some point. false for non-refundable rates. Absent when unknown.

    currency stringnullable

    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.

  • Array [
  • from stringnullable

    When this step starts (ISO 8601 with UTC offset). Absent means from the moment of booking, as for non-refundable rates.

    amount decimalnullable

    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.

  • ]
  • description stringnullable

    Cancellation policy as the supplier words it. Only returned by v2.0/orders/checkPrice, not by the search.

    supplier objectnullable
    name stringnullable

    Name of the supplier providing this rate.

    logo stringnullable

    URL of the supplier's logo. Absent when the credential has none on file.

    offers object[]nullable

    Promotional offers applied to the rate.

  • Array [
  • name stringnullable

    Offer name.

    discount numbernullable

    Discount value/percentage.

    freeNights integernullable

    Number of free nights granted by the offer, when applicable.

    discountType nullable

    Possible values: [STAY_DISCOUNT, DISCOUNT, FREE_NIGHT, LAST_MINUTE, null]

    Discount type.

    nightsRequired integernullable

    Nights required to qualify for the offer, when applicable.

  • ]
  • paymentOptions object[]nullable

    Payment/guarantee options accepted for this room.

  • Array [
  • id stringrequired

    Payment option ID: pass it as is to v2.0/orders/booking (payments[].paymentOptionId). Opaque: don't parse it.

    type required

    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.

    name stringnullable

    Display name for the payment option.

    description stringnullable

    Human-readable description.

    card objectnullable
    brands string[]nullable

    Accepted card brands, e.g. VISA, MASTERCARD. Absent when any brand is accepted.

    payLater objectnullable
    deadline stringnullable

    When the booking is cancelled automatically if not paid, ISO 8601 UTC. Absent when the supplier gives none.

  • ]
  • mealPlan objectnullable
    meals undefined[]

    Possible values: [breakfast, lunch, dinner]

    Meals included in the rate. An empty list means room only.

    allInclusive booleannullable

    true when the rate is all-inclusive: every meal and usually drinks and more. Absent otherwise.

    name stringnullable

    Meal plan name, as the supplier gives it.

    description stringnullable

    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
    id stringnullable

    Rate plan ID.

    name stringnullable

    Rate plan name.

    public booleannullable

    Whether the rate plan is publicly published.

    package booleannullable

    Whether the rate plan is a package (bundled with extras).

    description stringnullable

    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.

    promoCode stringnullable

    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.

  • Array [
  • name stringnullable

    Remark title, e.g. General Policies, Pets or Warning. Absent when the supplier gives none.

    description stringrequired

    Remark text.

  • ]
  • error objectnullable
    code stringrequired

    Stable code: SOLD_OUT, NOT_ENOUGH_UNITS (room) or NO_COMMON_PAYMENT_OPTION (item).

    message stringrequired

    Human-readable explanation.

  • ]
  • hotel objectnullable
    id stringrequired

    Internal Niara ID of the hotel.

    name stringrequired

    Hotel name.

    cityName stringnullable

    Name of the hotel's city.

    countryName stringnullable

    Name of the hotel's country.

    address stringnullable

    Hotel address.

    position objectnullable

    Geographic coordinates of the hotel.

    latitude numbernullable

    Latitude of the hotel.

    longitude numbernullable

    Longitude of the hotel.

    imageUrl stringnullable

    URL of the hotel's main image.

    detailsUrl stringnullable

    URL with the hotel's full descriptive content.

    rating integernullable

    Hotel star rating, when known.

    preferred boolean

    Whether this is one of the client's preferred hotels.

    total objectnullable
    amount decimalrequired

    Monetary amount.

    currency stringrequired

    Currency code (ISO 4217).

    previousTotal objectnullable
    amount decimalrequired

    Monetary amount.

    currency stringrequired

    Currency code (ISO 4217).

    paymentOptions object[]nullable

    Payment options every room of the item accepts. Only when commonPaymentOptions is on.

  • Array [
  • id stringrequired

    Payment option ID: pass it as is to v2.0/orders/booking (payments[].paymentOptionId). Opaque: don't parse it.

    type required

    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.

    name stringnullable

    Display name for the payment option.

    description stringnullable

    Human-readable description.

    card objectnullable
    brands string[]nullable

    Accepted card brands, e.g. VISA, MASTERCARD. Absent when any brand is accepted.

    payLater objectnullable
    deadline stringnullable

    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.

    person string[]

    Required inside person, when the party is sent as a person.

    company string[]

    Required inside company, when the party is sent as a company. vatNumber and corporateName are always required on top.

    primaryGuest string[]

    Required on each room's primary guest (rooms[].guests[].primary: true).

    secondaryGuests string[]

    Required on every other adult of each room. Empty unless the checkout form asks for every guest.

    children string[]

    Required instead of secondaryGuests, for a guest with type: CHILD. Empty unless the checkout form asks for every guest or for children.

    foreign string[]

    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.

    person string[]

    Required inside person, when the party is sent as a person.

    company string[]

    Required inside company, when the party is sent as a company. vatNumber and corporateName are always required on top.

    error objectnullable
    code stringrequired

    Stable code: SOLD_OUT, NOT_ENOUGH_UNITS (room) or NO_COMMON_PAYMENT_OPTION (item).

    message stringrequired

    Human-readable explanation.

  • ]
  • totals object[]

    Sum of the bookable items' totals, one entry per currency.

  • Array [
  • amount decimalrequired

    Monetary amount.

    currency stringrequired

    Currency code (ISO 4217).

  • ]
  • bookingToken stringnullable

    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.

    expiresAt stringnullable

    When bookingToken expires (15 minutes after the price check), ISO 8601 UTC.

    language stringnullable

    The language actually used for the texts.

Loading...