Hotel Rates API JSON Data Structure
Understanding the Pre-Booking Response Structure
When using LiteAPI’s Prebook API, the response returns a detailed object containing all the information required to review and confirm a room booking before finalizing payment. Below is an overview of the key fields included in the response, organized by their hierarchy and purpose.
⸻
Top-Level Response Structure
data
An array containing the booking details for each hotel involved in the prebook request.
⸻
Hotel Details (Inside data)
hotelId
The unique identifier for the hotel related to this pre-booking. Use this ID with the hotel content endpoint to retrieve hotel details.
roomTypes
An array of offers for this specific hotel. Rooms and Rates are used fairly interchangeably in the API If you think of it as each rate is for a specific room in the hotel, that helps. But since we support multiple room booking now, this is an array of offers that will have rate(s) based on how many occupancies were requested.
⸻
Room Type (Inside roomTypes) (More commonly called offers.)
An array containing the details for each offer for this specific hotel.
roomTypeId
This field is kept for legacy purposes but is not used or referenced.
offerId
This is the value needed to move to the prebook step. It contains all the needed data for all rates that are a part of this offer.
supplier
The supplier of the inventory (default is always “Nuitee”).
supplierId
Numeric identifier of the supplier (default Nuitee’s ID is 2).
rates
There are rates equal to the number of occupancies in the request. Each rate is tied to one of the requested occupancies.
⸻
Rate (Inside rates)
An array detailing the pricing and occupancy information for each rate associated with the room.
rateId
Unique ID for the rate within the offer. Normally it is not needed as it is rolled into the offerId above.
occupancyNumber
Reference number linking the rate to the specific occupancy request. Returned in order as 1,2,3... Use this number when assigning guests at the Book step.
name
Name of the room from the supplier, it may include key attributes (e.g., “Deluxe King Room – Ocean View”). This is an open field, so we dont have a list of valid types. If you want a specific room, call rates with "roomMapping":true to get the mappedRoomId
maxOccupancy
Maximum allowed occupancy for the room. This should at least match the occupancy.
adultCount
Number of adults included in the room.
childCount
Number of children included in the room.
boardType
Short code representing the meal plan (e.g., “RO” for Room Only).
Possible Values:
"boardResponses": [
{
"boardId": "RO",
"boardDescription": "Room Only"
},
{
"boardId": "BB",
"boardDescription": "Bed and Breakfast"
},
{
"boardId": "HB",
"boardDescription": "Half Board"
},
{
"boardId": "FB",
"boardDescription": "Full Board"
},
{
"boardId": "AI",
"boardDescription": "All Inclusive"
},
{
"boardId": "TI",
"boardDescription": "All Inclusive"
},
{
"boardId": "BD",
"boardDescription": "Breakfast and Dinner"
},
{
"boardId": "BL",
"boardDescription": "Breakfast and Lunch"
},
{
"boardId": "DI",
"boardDescription": "Dinner"
},
{
"boardId": "LU",
"boardDescription": "Lunch"
},
{
"boardId": "LD",
"boardDescription": "Lunch And Dinner"
},
{
"boardId": "RO",
"boardDescription": "Room Only"
},
{
"boardId": "BB",
"boardDescription": "Bed and Breakfast"
},
{
"boardId": "HB",
"boardDescription": "Half Board"
},
{
"boardId": "FB",
"boardDescription": "Full Board"
},
{
"boardId": "AI",
"boardDescription": "All Inclusive"
},
{
"boardId": "BB1",
"boardDescription": "Bed and Breakfast for 1"
},
{
"boardId": "HB1",
"boardDescription": "Half Board for 1"
},
{
"boardId": "FB1",
"boardDescription": "Full Board for 1"
},
{
"boardId": "AI1",
"boardDescription": "All Inclusive for 1"
},
{
"boardId": "BB2",
"boardDescription": "Bed and Breakfast for 2"
},
{
"boardId": "HB2",
"boardDescription": "Half Board for 2"
},
{
"boardId": "FB2",
"boardDescription": "Full Board for 2"
},
{
"boardId": "AI2",
"boardDescription": "All Inclusive for 2"
},
{
"boardId": "BB3",
"boardDescription": "Bed and Breakfast for 3"
},
{
"boardId": "HB3",
"boardDescription": "Half Board for 3"
},
{
"boardId": "FB3",
"boardDescription": "Full Board for 3"
},
{
"boardId": "AI3",
"boardDescription": "All Inclusive for 3"
},
{
"boardType": "BI",
"boardDescription": "Breakfast Included",
}
]
boardName
Full description of the meal plan (e.g., “Breakfast Included”). See the list above for possible values
remarks
Special remarks or notes for the room or rate.
priceType
Pricing model applied (e.g., “commission”). 'Currently we only support commission, though setting commission to 0, makes it a Net Rate.
⸻
Commission (Inside commission)
Details the commission applied to the rate.
amount
The commission amount included in the total rate.
currency
The currency used for the commission.
⸻
Total (Inside retailRate)
The total due to book this room. This includes any commission amount listed above and any taxes or fees listed as "included":true.
"retailRate": {
"total": [
{
"amount": 197.53,
"currency": "USD"
}
],
This only ever has an object labeled total, which will always have one item in its array containing an amount and a currency.
It this example 197.53 USD needs to be paid to book this room.
SSP (Inside suggestedSellingPrice)
This is the price you will find this room sold for publicly. When selling publicly, it is the price you need to display for the room. For more on how this works check out our Revenue Management Guide. We pull this number regularly from the hotel websites or popular OTAs.
"suggestedSellingPrice": [
{
"amount": 249.53,
"currency": "USD",
"source": "providerDirect"
}
],
initialPrice (Inside initialPrice)
This can usually be ignored as it requires a special contract with the hotels. If you have a direct relationship with a hotel, they can send you specific discounts, and in those cases, this initial price will be higher than the retail rate; the difference is the hotel's discount they are offering you.
"initialPrice": [
{
"amount": 197.53,
"currency": "USD"
}
],
Taxes or Fees (Inside taxesAndFees)
Suppliers are required to disclose all fees like pay at property, but are not required to display fees and taxes that are included in the rate. This means this value can be returned in multiple formats. each one has four possible fields.
included
This value will be either true or false and lets you know if the amount is included in the retailRate. When trueIt was already calculated into the rate, but if false, it means they will need to pay this amount when they arrive at the property.
Here are some of the most common formats.
Here we have an example of the best kind of data you can hope for; every fee is clearly delineated and broken out into discrete values.
"taxesAndFees": [
{
"included": true,
"description": "NYC Javits Center Fee",
"amount": 1.62,
"currency": "USD"
},
{
"included": true,
"description": "NYC Occupancy Tax",
"amount": 2.16,
"currency": "USD"
},
{
"included": true,
"description": "NY State Tax",
"amount": 11.88,
"currency": "USD"
},
{
"included": true,
"description": "NY City Tax",
"amount": 7.87,
"currency": "USD"
},
{
"included": false,
"description": "Facility Fee",
"amount": 43.61,
"currency": "USD"
}
]
We get very similar data in this example, but the specific descriptions are obfuscated. It works the same way, but the fees and taxes have been combined. The only separation here is between values that are included and those that are excluded.
"taxesAndFees": [
{
"included": true,
"description": "OTHERS",
"amount": 94.91,
"currency": "USD"
},
{
"included": false,
"description": "RESORT",
"amount": 21.78,
"currency": "USD"
}
]
In this final example, we get the least informative data back. It's just null not even an empty array. Here, we are told nothing about the taxes and fees that are included. However, since they are required to disclose not included fees, this means that all taxes and fees are included in this booking.
"taxesAndFees": null
Cancellation Policies(cancellationPolicies)
This section details all the applicable policies related to canceling a booking.
cancelPolicyInfos
This contains all the time-bound policies for this booking. Check out the cancelation guide for examples and details on how these policies work.
hotelRemarks
Lists any special remarks from the hotel about their cancellation policies.
refundableTag
This will be either NRFN (non-refundable) or RFN (refundable).
In this example, we see a non-refundable booking, but it still refunds all but $59 of a nearl $200 booking, which is why sometimes users may still want to cancel a NRFN booking. A booking is considered NRFN if ANY portion of the booking is not refunded.
"cancellationPolicies": {
"cancelPolicyInfos": [
{
"cancelTime": "2025-05-13 12:41:00",
"amount": 59.25,
"currency": "USD",
"type": "amount",
"timezone": "GMT"
},
{
"cancelTime": "2025-07-29 04:00:00",
"amount": 197.53,
"currency": "USD",
"type": "amount",
"timezone": "GMT"
}
],
"hotelRemarks": [],
"refundableTag": "NRFN"
},
Back to the roomTypes
After going through all the different rates on this offer, we need to add them together for the whole offer. If you are only looking for one room/rate then this seems very duplicative, but if you have two or more rooms then this section adds up everything so you can easily understand values at the offer level.
offerRetailRate
Here we get the total amount in our requestedcurrency that is needed to book this room. This includes any applicable commission and included taxes or fees from across all the rates. If you manually add up all the retail rates for each rate in this offer, it should equal this amount. If you only have one rate, then these should be the same.
In this example $220.54 is needed to book this offer.
"offerRetailRate": {
"amount": 220.54,
"currency": "USD"
},
suggestedSellingPrice
This is the combined SSP across all the rates of this offer. This amount in the specified currencyis how much the entire offer needs to be listed for publicly. Alternatively, the difference is the amount of discount you are passing to members of your closed user group. The source is not disclosed and will display providerDirect
"suggestedSellingPrice": {
"amount": 262.57,
"currency": "USD",
"source": "providerDirect"
},
offerInitialPrice
This is the combined hotel price. Usually this can be ignored. See above for usecases where it may matter.
"offerInitialPrice": {
"amount": 220.54,
"currency": "USD"
},
rate and price Type
priceType
Currently, we only support commission. Though you can set commission to 0 to get Net Rates, but they still are called commission
rateType
This can be standard or package. If you have a usecase where you bundle products and or services together, contact us or your sales rep so we can enable package rates for you.
Back to the data level
guestLevel
This is for possible use in the future, currently always set to 0.
"guestLevel": 0
Updated 24 days ago