Skip to main content

Order

POST 

/v2.0/orders/details

Introduction​

Reads a previously created order, by its orderId or by your externalReference.

A reference reads its order. If every booking attempt with it failed, it reads the last attempt. status is FAILED exactly when the order's reference can be booked again.

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.

    orderId stringnullable

    ID of the order, as returned by orderId on the booking response.

    externalReference stringnullable

    Your externalReference for the order, as sent to v2.0/orders/booking. Useful when you don't have the orderId, e.g. after a booking timed out. If every attempt with it failed, reads the last one.

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

    Purchase order ID.

    externalReference stringnullable

    Your externalReference for the order, as sent to v2.0/orders/booking.

    status required

    Possible values: [INPROGRESS, CONFIRMED, CANCELLED, FAILED]

    Derived from the items: INPROGRESS while any is; CANCELLED when all are; FAILED when none got booked; otherwise CONFIRMED.

    createdAt stringnullable

    When the order was created.

    updatedAt stringnullable

    When the order was last updated.

    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.

    items object[]

    The items that make up the order. Each has the schema of its type.

  • Array [
  • type required

    Possible values: [hotel]

    Product type: hotel.

    ref stringnullable

    The item's ref, as sent to v2.0/orders/booking. Absent for a reservation made before this field started being saved.

    status required

    Possible values: [INPROGRESS, CONFIRMED, CANCELLED, FAILED]

    INPROGRESS while any room is; CANCELLED when all are; FAILED when none got booked; otherwise CONFIRMED.

    hotel objectrequired
    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.

    checkin stringrequired

    Check-in date.

    checkout stringrequired

    Check-out date.

    total objectnullable
    amount decimalrequired

    Monetary amount.

    currency stringrequired

    Currency code (ISO 4217).

    comments stringnullable

    Comments sent for the hotel at booking, combined with any per-room special request.

    rooms object[]

    The item's rooms.

  • Array [
  • ref stringnullable

    The room's ref, as sent to v2.0/orders/booking. Absent for a reservation made before this field started being saved.

    reservationId stringrequired

    The ID the booking response returned and Cancel accepts.

    status required

    Possible values: [INPROGRESS, CONFIRMED, CANCELLED, FAILED]

    See the order-level status for the mapping from internal states.

    confirmationCode stringnullable

    The supplier's or hotel's locator: what the guest shows at check-in.

    cancelledAt stringnullable

    When the room was cancelled. Only present when status is CANCELLED.

    cancellationFee objectnullable
    amount decimalrequired

    Monetary amount.

    currency stringrequired

    Currency code (ISO 4217).

    cancellation objectnullable
    status required

    Possible values: [FAILED]

    Only value for now: the cancellation attempt failed.

    message stringnullable

    Why it failed, when known.

    occupancy objectrequired
    adults integerrequired

    Number of adults per room.

    childrenAges integer[]

    Ages of the children per room.

    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.

    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.

    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.

  • ]
  • 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.

  • ]
  • guests object[]

    Guests staying in the room.

  • 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
  • ]
  • ]
  • ]
  • totals object[]

    Sum of the items' total, one entry per currency.

  • Array [
  • amount decimalrequired

    Monetary amount.

    currency stringrequired

    Currency code (ISO 4217).

  • ]
  • payments object[]

    Payments towards the order.

  • Array [
  • type stringrequired

    The payment option's type: CREDITCARD, PAY_AT_PROPERTY, INVOICE or PAY_LATER.

    status required

    Possible values: [PENDING, AUTHORIZED, PAID, REFUNDED, FAILED, CANCELLED, DISPUTED]

    PENDING also covers a payment type Niara doesn't track to completion, such as PAY_AT_PROPERTY.

    amount objectrequired
    amount decimalrequired

    Monetary amount.

    currency stringrequired

    Currency code (ISO 4217).

    refunded objectnullable
    amount decimalrequired

    Monetary amount.

    currency stringrequired

    Currency code (ISO 4217).

    installments integernullable

    Number of installments.

    card objectnullable
    brand stringnullable

    Card brand.

    last4 stringnullable

    Card's last 4 digits.

    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.

    paidItems object[]

    Which item(s) this payment covers, and how much of each.

  • 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
  • ]
  • ]
Loading...