See below a few best practices that we recommend you should follow when writing to our API.
- Sending Multiple IDs in a Single getPropertyByIds Request
- Price Variance at Quote and Book Steps
- Mandatory and Optional Attributes for Search
Sending Multiple IDs in a Single getPropertyByIds Request
Technically there is no limit on the number of IDs that can be sent in a single request. However, there are implications to the response time as the number of IDs being queried increases.
To better understand this, refer to the example below:
Response size for 1 property with 10 rooms = ~20kb
Assuming that all properties have availability 10 rooms
Response size for 50 properties with 10 rooms = 50 x 20 = ~1000kb.
As the size of the response payload impacts the response time, we strongly suggest limiting the number of properties to 50 in a single request.
In case you need availability for more than 50 properties, parallel calls should be made for the Search API. There is no limit on the number of parallel calls that can be requested.
Price Variance at Quote and Book Steps
For each price returned in the search request, a unique htIdentifier is generated. This ID is valid for 30 minutes. To confirm a reservation, a Search step will be followed by the Quote and Book request using the htIdentifier obtained in the Search response. If your system allows for a certain variance in the price to go higher, then you can continue to use the same htIdentifier in the Quote and the Book step.
In our systems, the prices are updated in real-time. Therefore, the prices generated at the Search step might change within the 30-minute window. In such cases, the Quote requests will still return a successful response and updated prices will be sent in as part of the response. The grossPriceChanged is true when there has been a price change. You can proceed to book with updated prices.
Check for the grossPriceChanged attribute and proceed with updated prices only if is is true.
The following example shows the response sent when there has been a price change. The grossPriceChanged attribute is set to true.
{
"quote": {
"aggregateGrossPrice": 330.18,
"aggregateNetPrice": 300.17,
"aggregateTax": 30.01,
"aggregatePayAtProperty": 50,
"consolidatedComments": "Free Breakfast. A Resort Fee totaling EUR50.00 will be charged for the stay. Mandatory Charge. Plus applicable taxes.. Hotel Check In Policy: Major credit card required at check-in for deposit and incidentals. Any additional fees such as parking, pet fees, etc. are solely at the discretion of the hotel, are subject to change at any point and should be paid directly by the guest.. Minimum adult age at check in is 21 years.",
"rooms": [
{
"htIdentifier": "6131514161|1312101315121|1419131812141|121012131-112-11101|121012131-112-112|1816101c121e16131-1e1816131-141d1f131-191a16191-131416191715191d1b13201|1116192315111814131113191|1O1D1C22131|1K111",
"grossPriceChanged": false,
"message": "Confirm Price Success. Please proceed to Book stage.",
"cancellationPolicies": [
{
"startWindowTime": "2023-11-09 23:59:00",
"endWindowTime": "2023-11-10 16:00:00",
"currency": "EUR",
"cancellationCharge": 330.18,
"timeZone": "Europe/Istanbul",
"timeZoneUTC": "+03:00"
}
],
"mealplanOptions" : {
"mealplanDescription": "Free Breakfast",
"mealplanCode": "BBF",
"mealplanName": "Free Breakfast"
},
"rates": {
"bar": null,
"binding": null,
"commissionable": false,
"commissionAmount": null,
"currency": "EUR",
"netPrice": 300.17,
"tax": 30.01,
"grossPrice": 330.18,
"payAtProperty": 50,
"dailyPrice": [
300.17
],
"dailyTax": [
30.01
],
"aggregateTaxInfo": {
"payAtBooking": [
{
"description": null,
"name": "percent",
"currency": "EUR",
"value": 30.01
}
],
"payAtProperty": [
{
"description": "Mandatory Charge. Plus applicable taxes.",
"name": "Mandatory Charge",
"currency": "EUR",
"value": 50
}
]
}
}
}
]
}
}
Mandatory and Optional Attributes for Search
There are some attributes that you must query for when you perform a search. Should the search convert into a booking request, you will need to pass the values that were obtained in the Search response.
Visit the Mandatory vs Optional Attributes page for a complete list of attributes that must be included in every search query.