Skip to main content

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​

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.

    bookingToken stringrequired

    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.

  • Array [
  • type required

    Possible values: [hotel]

    Product type: hotel. Must match the item's type in the price check.

    ref stringrequired

    The item's ref, as sent to (and returned by) v2.0/orders/checkPrice.

    expectedTotal objectrequired
    amount decimalrequired

    Monetary amount.

    currency stringrequired

    Currency code (ISO 4217).

    rooms object[]required

    Every room of the item from the price check, each exactly once.

  • Array [
  • ref stringrequired

    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.

  • Array [
  • firstName stringrequired

    Guest's first name.

    lastName stringnullable
    dob stringnullable

    Date of birth (ISO 8601).

    nationality stringnullable

    ISO 3166-1 alpha-2.

    email stringnullable
    phone stringnullable
    address objectnullable
    street stringnullable
    number stringnullable
    complement stringnullable
    district stringnullable
    city stringnullable
    state stringnullable

    State or province, e.g. SP.

    zipCode stringnullable

    Postal code.

    country stringnullable

    The address country, ISO 3166-1 alpha-2.

    documents objectnullable
    cpf stringnullable

    Brazilian CPF. Punctuation is accepted; check digits are validated.

    rg objectnullable
    number stringnullable
    issuer stringnullable

    Issuing organ, e.g. SSP-SP. Only with number.

    passport objectnullable
    number stringnullable
    birthCertificate stringnullable

    Birth certificate number. Only kept for guests.

    other objectnullable
    type stringnullable

    Document type, e.g. CO_CC.

    number stringnullable
    type required

    Possible values: [ADULT, CHILD]

    Age category of the guest.

    primary boolean

    Whether this is the room's primary guest. Must be ADULT; exactly one per room.

    age integernullable
  • ]
  • specialRequests stringnullable

    Free-text special requests for this room, sent to the hotel after the item's comments.

  • ]
  • comments stringnullable

    Free-text comments for the hotel (e.g. late check-in), sent with every room of the item.

  • ]
  • buyer objectrequired
    person objectnullable
    firstName stringnullable
    lastName stringnullable
    dob stringnullable

    Date of birth (ISO 8601).

    nationality stringnullable

    ISO 3166-1 alpha-2.

    email stringnullable
    phone stringnullable
    address objectnullable
    street stringnullable
    number stringnullable
    complement stringnullable
    district stringnullable
    city stringnullable
    state stringnullable

    State or province, e.g. SP.

    zipCode stringnullable

    Postal code.

    country stringnullable

    The address country, ISO 3166-1 alpha-2.

    documents objectnullable
    cpf stringnullable

    Brazilian CPF. Punctuation is accepted; check digits are validated.

    rg objectnullable
    number stringnullable
    issuer stringnullable

    Issuing organ, e.g. SSP-SP. Only with number.

    passport objectnullable
    number stringnullable
    birthCertificate stringnullable

    Birth certificate number. Only kept for guests.

    other objectnullable
    type stringnullable

    Document type, e.g. CO_CC.

    number stringnullable
    company objectnullable
    vatNumber stringnullable

    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.

    corporateName stringnullable

    Legal name ("razão social").

    brandName stringnullable

    Trade name ("nome fantasia").

    stateRegistration stringnullable

    Brazilian state tax registration ("inscrição estadual").

    municipalRegistration stringnullable

    Brazilian municipal tax registration ("inscrição municipal").

    email stringnullable
    phone stringnullable
    address objectnullable
    street stringnullable
    number stringnullable
    complement stringnullable
    district stringnullable
    city stringnullable
    state stringnullable

    State or province, e.g. SP.

    zipCode stringnullable

    Postal code.

    country stringnullable

    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.

  • Array [
  • paymentOptionId stringrequired

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

    Card brand, e.g. VISA. Must be one of the option's card.brands, when it lists any.

    holder stringnullable

    Cardholder name, as on the card.

    number stringnullable
    expiryDate stringnullable

    Expiry as MMYY, e.g. 1230.

    cvv stringnullable
    installments integer

    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.

  • Array [
  • itemRef stringrequired

    The item (items[].ref) this portion of the payment applies to.

    amount decimalrequired

    Portion of that item's total covered by this payment. Split across the item's rooms by room price.

    currency stringrequired
  • ]
  • payer objectnullable
    person objectnullable
    firstName stringnullable
    lastName stringnullable
    dob stringnullable

    Date of birth (ISO 8601).

    nationality stringnullable

    ISO 3166-1 alpha-2.

    email stringnullable
    phone stringnullable
    address objectnullable
    street stringnullable
    number stringnullable
    complement stringnullable
    district stringnullable
    city stringnullable
    state stringnullable

    State or province, e.g. SP.

    zipCode stringnullable

    Postal code.

    country stringnullable

    The address country, ISO 3166-1 alpha-2.

    documents objectnullable
    cpf stringnullable

    Brazilian CPF. Punctuation is accepted; check digits are validated.

    rg objectnullable
    number stringnullable
    issuer stringnullable

    Issuing organ, e.g. SSP-SP. Only with number.

    passport objectnullable
    number stringnullable
    birthCertificate stringnullable

    Birth certificate number. Only kept for guests.

    other objectnullable
    type stringnullable

    Document type, e.g. CO_CC.

    number stringnullable
    company objectnullable
    vatNumber stringnullable

    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.

    corporateName stringnullable

    Legal name ("razão social").

    brandName stringnullable

    Trade name ("nome fantasia").

    stateRegistration stringnullable

    Brazilian state tax registration ("inscrição estadual").

    municipalRegistration stringnullable

    Brazilian municipal tax registration ("inscrição municipal").

    email stringnullable
    phone stringnullable
    address objectnullable
    street stringnullable
    number stringnullable
    complement stringnullable
    district stringnullable
    city stringnullable
    state stringnullable

    State or province, e.g. SP.

    zipCode stringnullable

    Postal code.

    country stringnullable

    The address country, ISO 3166-1 alpha-2.

  • ]
  • externalReference stringrequired

    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 stringnullable

    Language for the texts: pt-BR, en-US or es-ES. Defaults to the language of the price check.

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.

    orderId stringrequired
    externalReference stringrequired

    Your externalReference for the order, as sent.

    status required

    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.

  • Array [
  • type required

    Possible values: [hotel]

    Product type: hotel.

    ref stringrequired

    The item's ref.

    rooms object[]required

    The item's rooms, in the order sent.

  • Array [
  • ref stringrequired

    The room's ref.

    reservationId stringnullable

    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.

  • Array [
  • id stringrequired

    ID of the reservation whose price changed.

    itemRef stringnullable

    The item the room belongs to.

    roomRef stringnullable

    The room whose price changed.

    referenceTotal decimalnullable

    The total price this room was booked at.

    supplierTotal decimalnullable

    The room's current, live total price.

    difference decimalnullable
    currency stringnullable
  • ]
Loading...