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
- application/json
Body
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.
ID of the order, as returned by orderId on the booking response.
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
- 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.
Purchase order ID.
Your externalReference for the order, as sent to v2.0/orders/booking.
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.
When the order was created.
When the order was last updated.
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.
items object[]
The items that make up the order. Each has the schema of its type.
Possible values: [hotel]
Product type: hotel.
The item's ref, as sent to v2.0/orders/booking. Absent for a reservation made before this field started being saved.
Possible values: [INPROGRESS, CONFIRMED, CANCELLED, FAILED]
INPROGRESS while any room is; CANCELLED when all are; FAILED when none got booked; otherwise CONFIRMED.
hotel objectrequired
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.
Check-in date.
Check-out date.
total objectnullable
Monetary amount.
Currency code (ISO 4217).
Comments sent for the hotel at booking, combined with any per-room special request.
rooms object[]
The item's rooms.
The room's ref, as sent to v2.0/orders/booking. Absent for a reservation made before this field started being saved.
The ID the booking response returned and Cancel accepts.
Possible values: [INPROGRESS, CONFIRMED, CANCELLED, FAILED]
See the order-level status for the mapping from internal states.
The supplier's or hotel's locator: what the guest shows at check-in.
When the room was cancelled. Only present when status is CANCELLED.
cancellationFee objectnullable
Monetary amount.
Currency code (ISO 4217).
cancellation objectnullable
Possible values: [FAILED]
Only value for now: the cancellation attempt failed.
Why it failed, when known.
occupancy objectrequired
Number of adults per room.
Ages of the children per room.
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.
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.
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.
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.
guests object[]
Guests staying in the room.
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.
totals object[]
Sum of the items' total, one entry per currency.
Monetary amount.
Currency code (ISO 4217).
payments object[]
Payments towards the order.
The payment option's type: CREDITCARD, PAY_AT_PROPERTY, INVOICE or PAY_LATER.
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
Monetary amount.
Currency code (ISO 4217).
refunded objectnullable
Monetary amount.
Currency code (ISO 4217).
Number of installments.
card objectnullable
Card brand.
Card's last 4 digits.
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.
paidItems object[]
Which item(s) this payment covers, and how much of each.
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.
{
"requestId": "string",
"externalRequestId": "string",
"timestamp": "string",
"orderId": "string",
"externalReference": "string",
"createdAt": "string",
"updatedAt": "string",
"buyer": {
"person": {
"firstName": "string",
"lastName": "string",
"dob": "string",
"nationality": "string",
"email": "string",
"phone": "string",
"address": {
"street": "string",
"number": "string",
"complement": "string",
"district": "string",
"city": "string",
"state": "string",
"zipCode": "string",
"country": "string"
},
"documents": {
"cpf": "string",
"rg": {
"number": "string",
"issuer": "string"
},
"passport": {
"number": "string"
},
"birthCertificate": "string",
"other": {
"type": "string",
"number": "string"
}
}
},
"company": {
"vatNumber": "string",
"corporateName": "string",
"brandName": "string",
"stateRegistration": "string",
"municipalRegistration": "string",
"email": "string",
"phone": "string",
"address": {
"street": "string",
"number": "string",
"complement": "string",
"district": "string",
"city": "string",
"state": "string",
"zipCode": "string",
"country": "string"
}
}
},
"items": [
{
"ref": "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
},
"checkin": "string",
"checkout": "string",
"total": {
"amount": "string",
"currency": "string"
},
"comments": "string",
"rooms": [
{
"ref": "string",
"reservationId": "string",
"confirmationCode": "string",
"cancelledAt": "string",
"cancellationFee": {
"amount": "string",
"currency": "string"
},
"cancellation": {
"message": "string"
},
"occupancy": {
"adults": 0,
"childrenAges": [
0
]
},
"roomType": {
"id": "string",
"name": "string",
"description": "string"
},
"mealPlan": {
"meals": [
null
],
"allInclusive": true,
"name": "string",
"description": "string"
},
"ratePlan": {
"id": "string",
"name": "string",
"public": true,
"package": true,
"description": "string"
},
"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"
}
]
}
},
"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
}
]
},
"guests": [
{
"firstName": "string",
"lastName": "string",
"dob": "string",
"nationality": "string",
"email": "string",
"phone": "string",
"address": {
"street": "string",
"number": "string",
"complement": "string",
"district": "string",
"city": "string",
"state": "string",
"zipCode": "string",
"country": "string"
},
"documents": {
"cpf": "string",
"rg": {
"number": "string",
"issuer": "string"
},
"passport": {
"number": "string"
},
"birthCertificate": "string",
"other": {
"type": "string",
"number": "string"
}
},
"primary": false,
"age": 0
}
]
}
]
}
],
"totals": [
{
"amount": "string",
"currency": "string"
}
],
"payments": [
{
"type": "string",
"amount": {
"amount": "string",
"currency": "string"
},
"refunded": {
"amount": "string",
"currency": "string"
},
"installments": 0,
"card": {
"brand": "string",
"last4": "string"
},
"payer": {
"person": {
"firstName": "string",
"lastName": "string",
"dob": "string",
"nationality": "string",
"email": "string",
"phone": "string",
"address": {
"street": "string",
"number": "string",
"complement": "string",
"district": "string",
"city": "string",
"state": "string",
"zipCode": "string",
"country": "string"
},
"documents": {
"cpf": "string",
"rg": {
"number": "string",
"issuer": "string"
},
"passport": {
"number": "string"
},
"birthCertificate": "string",
"other": {
"type": "string",
"number": "string"
}
}
},
"company": {
"vatNumber": "string",
"corporateName": "string",
"brandName": "string",
"stateRegistration": "string",
"municipalRegistration": "string",
"email": "string",
"phone": "string",
"address": {
"street": "string",
"number": "string",
"complement": "string",
"district": "string",
"city": "string",
"state": "string",
"zipCode": "string",
"country": "string"
}
}
},
"paidItems": [
{
"itemRef": "string",
"amount": "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"
}
]
}
}