Prebook
https://api.worldota.net/api/b2b/v3/hotel/prebook/
The call checks if the requested rate is still available before it can be booked and improves the booking success rate:
-
If the original rate is unavailable, the call will try to find the same or similar rate with the new
book_hash
andmatch_hash
field values. -
If:
- The same rate isn’t found.
- The request specifies a permissible price increase in the
price_increase_percent
field.
The call will try to find the same room but with an increased price. The value in the
payment_options
field may change.
The limitations:
- The recommended call timeout is 60 seconds.
- The minimum call timeout is 30 seconds.
Request example
curl --user <KEY_ID>:<API_KEY> 'https://api.worldota.net/api/b2b/v3/hotel/prebook' \
--header 'Content-Type: application/json' \
--data '{
"hash": "h-154bd176-8db0-5fbd-b169-1df3b43d1fc0",
"price_increase_percent": 20
}'
Request body
The unique rate ID.
Use this value within 24 hours after the Hotelpage call returns a relevant rate.
- The minimum length is
1
character. - The maximum length is
256
characters.
The percentage by which the new price can be higher than the original price.
For example, if you send price_increase_percent=20
and the starting price is 1,000, the maximum allowed price for this pre-book call is 1,200.
If the value isn’t provided, the API will try to rebook with the same price or lower.
- The minimum value is
0
. - The maximum value is
100
.
Response
The list of hotels and their rates.
The most preferred hotel ID.
- Either this field or the
id
field is required. - The maximum length is
7
characters.
The list of available hotel rates.
Whether the rate is allowed to be booked by the guest with any kind of residency or not.
Use it if you don’t collect the guests’ residency.
The unique rate ID used to identify the selected rate.
- Use this value in the
book_hash
field of the Order Booking Form call. - The value lifetime is 6 hours after you have got the rate from the search results.
The deposit information of the order. Has a value if the rate payment_types.type
field has the hotel
value.
The match_hash
field of the rate from the call made by the SERP mechanism.
Use this field if you are:
- Showing rates to the users from the call made by the SERP mechanism.
- Making a booking from these rates.
- Using this call response as actual data on the rate.
- Using this call response to actualize the exact rate from the calls made by the SERP mechanism.
Usage of this field can help the ETG collect analytics for SERP-HP matching.
The meal type in the rate.
To get all available meal types and their definitions, use the meals
field from the Hotel Static Data call.
Has the nomeal
value if no meal type is provided.
The rate meals information.
The meal type in the rate.
To get all available meal types and their definitions, use the meals
field from the Hotel Static Data call.
Has the nomeal
value if no meal type is provided.
The no-show penalty information.
The accepted payment options with the specified amount to be charged.
For a booking, this amount in the requested currency should be paid.
The list with accepted payment options.
The cancellation rules and commission information.
The date and time when the free cancellation policy expires.
Has the null
value, if there is no free cancellation.
The timezone is in UTC±0.
The cancellation policies breakdown by periods.
The commission information.
The date and time when this cancellation policy expires.
Has the null
value, if it is in the time from the start_at
field value till check-in.
If the start_at
and end_at
fields have the null
value, this particular cancellation policy:
- Has no time restrictions.
- Is in effect all the time.
The timezone is in UTC±0.
The commission information.
The additional services’ information.
The early check-in information.
The commission information.
The late check-out information.
The commission information.
The price below which the rate can’t be sold on B2C website.
To get this value, you have to sign an additional agreement with the ETG. Has the null
value, ff the agreement isn’t signed. For more details, contact your account manager.
The rate price in the request currency code of this object show_currency_code
field value.
Isn’t necessarily the sum in the charged or payment currency code.
The tax information.
The taxes list.
The tax amount currency code in the ISO 4217 format.
- The length is
3
characters. - The possible values:
AED
.AFN
.ALL
.AMD
.ANG
.AOA
.ARS
.AUD
.AWG
.AZN
.BAM
.BBD
.BDT
.BGN
.BHD
.BIF
.BMD
.BND
.BOB
.BOV
.BRL
.BSD
.BTN
.BWP
.BYR
.BYN
.BZD
.CAD
.CDF
.CHE
.CHF
.CHW
.CLF
.CLP
.CNY
.COP
.COU
.CRC
.CUC
.CUP
.CVE
.CZK
.DJF
.DKK
.DOP
.DZD
.EGP
.ERN
.ETB
.EUR
.FJD
.FKP
.GBP
.GEL
.GHS
.GIP
.GMD
.GNF
.GTQ
.GYD
.HKD
.HNL
.HRK
.HTG
.HUF
.IDR
.ILS
.INR
.IQD
.IRR
.ISK
.JMD
.JOD
.JPY
.KES
.KGS
.KHR
.KMF
.KPW
.KRW
.KWD
.KYD
.KZT
.LAK
.LBP
.LKR
.LRD
.LSL
.LTL
.LVL
.LYD
.MAD
.MDL
.MGA
.MKD
.MMK
.MNT
.MOP
.MRO
.MUR
.MVR
.MWK
.MXN
.MXV
.MYR
.MZN
.NAD
.NGN
.NIO
.NOK
.NPR
.NZD
.OMR
.PAB
.PEN
.PGK
.PHP
.PKR
.PLN
.PYG
.QAR
.RON
.RSD
.RUB
.RWF
.SAR
.SBD
.SCR
.SDG
.SEK
.SGD
.SHP
.SLL
.SOS
.SRD
.SSP
.STD
.SVC
.SYP
.SZL
.THB
.TJS
.TMT
.TND
.TOP
.TRY
.TTD
.TWD
.TZS
.UAH
.UGX
.USD
.USN
.USS
.UYI
.UYU
.UZS
.VEF
.VND
.VUV
.WST
.XAF
.XAG
.XAU
.XBA
.XBB
.XBC
.XBD
.XCD
.XDR
.XFU
.XOF
.XPD
.XPF
.XPT
.XSU
.XTS
.XUA
.YER
.ZAR
.ZMW
.ZWL
.
Whether the tax is included by the supplier or not.
When it has:
- The
false
value, the tax is supposed to be paid at the hotel in this object currency. - The
true
value, the tax is included in the price.
The ETG tax ID.
To get all available tax IDs and their definitions, use the taxes
filed from the Hotel Static Data call.
The rate VAT information.
The amount currency code in the ISO 4217 format.
- The length is
3
characters. - The possible values:
AED
.AFN
.ALL
.AMD
.ANG
.AOA
.ARS
.AUD
.AWG
.AZN
.BAM
.BBD
.BDT
.BGN
.BHD
.BIF
.BMD
.BND
.BOB
.BOV
.BRL
.BSD
.BTN
.BWP
.BYR
.BYN
.BZD
.CAD
.CDF
.CHE
.CHF
.CHW
.CLF
.CLP
.CNY
.COP
.COU
.CRC
.CUC
.CUP
.CVE
.CZK
.DJF
.DKK
.DOP
.DZD
.EGP
.ERN
.ETB
.EUR
.FJD
.FKP
.GBP
.GEL
.GHS
.GIP
.GMD
.GNF
.GTQ
.GYD
.HKD
.HNL
.HRK
.HTG
.HUF
.IDR
.ILS
.INR
.IQD
.IRR
.ISK
.JMD
.JOD
.JPY
.KES
.KGS
.KHR
.KMF
.KPW
.KRW
.KWD
.KYD
.KZT
.LAK
.LBP
.LKR
.LRD
.LSL
.LTL
.LVL
.LYD
.MAD
.MDL
.MGA
.MKD
.MMK
.MNT
.MOP
.MRO
.MUR
.MVR
.MWK
.MXN
.MXV
.MYR
.MZN
.NAD
.NGN
.NIO
.NOK
.NPR
.NZD
.OMR
.PAB
.PEN
.PGK
.PHP
.PKR
.PLN
.PYG
.QAR
.RON
.RSD
.RUB
.RWF
.SAR
.SBD
.SCR
.SDG
.SEK
.SGD
.SHP
.SLL
.SOS
.SRD
.SSP
.STD
.SVC
.SYP
.SZL
.THB
.TJS
.TMT
.TND
.TOP
.TRY
.TTD
.TWD
.TZS
.UAH
.UGX
.USD
.USN
.USS
.UYI
.UYU
.UZS
.VEF
.VND
.VUV
.WST
.XAF
.XAG
.XAU
.XBA
.XBB
.XBC
.XBD
.XCD
.XDR
.XFU
.XOF
.XPD
.XPF
.XPT
.XSU
.XTS
.XUA
.YER
.ZAR
.ZMW
.ZWL
.
The hotel room type.
Use this field to get extra data on the room from the hotel static data. For example, room images, descriptions.
The room bathroom information.
The possible values:
0
—undefined.1
—a shared bathroom.2
—a private bathroom.3
—an external private bathroom.
The room bedding information.
The possible values:
0
—undefined.1
—a bunk bed.2
—a single bed.3
—a double bed.4
—a twin bed.7
—multiple beds.
The bedroom number.
The possible values:
0
—undefined.1
—1 bedroom.2
—2 bedrooms.3
—3 bedrooms.4
—4 bedrooms.5
—5 bedrooms.6
—6 bedrooms.
The maximum number of main bed places without additional charges and excluding extra beds, cots, etc.
The possible values:
0
—undefined.1
—single.2
—double.3
—triple.4
—quadruple.5
—quintuple.6
—sextuplet.
The room class information.
The possible values:
0
—run of house.1
—dorm.2
—capsule.3
—room.4
—junior suite.5
—suite.6
—apartment.7
—studio.8
—villa.9
—cottage.17
—bungalow.18
—chalet.19
—camping.20
—tent.
Whether it is a club room or not.
The possible values:
0
—not a club room.1
—a club room.
Whether it is a family room or not.
The possible values:
0
—not a family room.1
—a family room.
The room floor Information.
The possible values:
0
—undefined.1
—a penthouse floor.2
—a duplex floor.3
—a basement floor.4
—an attic floor.
The room quality information.
The possible values:
0
—undefined.1
—economy.2
—standard.3
—comfort.4
—business.5
—superior.6
—deluxe.7
—premier.8
—executive.9
—presidential.17
—premium.18
—classic.19
—ambassador.20
—grand.21
—luxury.22
—platinum.23
—prestige.24
—privilege.25
—royal.
The room gender restrictions.
The possible values:
0
—undefined.1
—male.2
—female.3
—mixed.
The room view information.
The possible values:
0
—undefined.1
—bay view.2
—bosphorus view.3
—burj-khalifa view.4
—canal view.5
—city view.6
—courtyard view.7
—dubai-marina view.8
—garden view.9
—golf view.17
—harbour view.18
—inland view.19
—kremlin view.20
—lake view.21
—land view.22
—mountain view.23
—ocean view.24
—panoramic view.25
—park view.26
—partial-ocean view.27
—partial-sea view.28
—partial view.29
—pool view.30
—river view.31
—sea view.32
—sheikh-zayed view.33
—street view.34
—sunrise view.35
—sunset view.36
—water view.37
—with view.38
—beachfront.39
—ocean front.40
—sea front.
The room information in the request language.
The hotel and service provider legal information.
Has the value different from null
for only countries where it is mandatory to have this information.
Has the null
value for the calls made by the SERP mechanism.
The hotel legal information.
The Taxpayer Personal Identification Number (INN) of the hotel.
- The length is
10
characters.
The State Registration Number for Companies (OGRN) of the hotel.
- The length is
13
characters.
The service provider legal information.
The Taxpayer Personal Identification Number (INN) of the service provider.
- The length is
10
characters.
Information on the restrictions on the final selling price for the client.
If not null
, the final selling price should be:
- Within the
min_price
andmax_price
field values. - In the search currency.
Response example
{
"data": {
"hotels": [
{
"id": "test_hotel_do_not_book",
"hid": 8473727,
"rates": [
{
"book_hash": "p-db3a23ed-6e5d-415c-b3df-1a11bc398340",
"match_hash": "m-672938ea-3bd0-5f9c-85a0-0da2d6c08f7d",
"daily_prices": [
"2.00"
],
"meal": "breakfast",
"meal_data": {
"value": "breakfast",
"has_breakfast": true,
"no_child_meal": false
},
"payment_options": {
"payment_types": [
{
"amount": "1.00",
"show_amount": "2.00",
"currency_code": "GBP",
"show_currency_code": "USD",
"by": null,
"is_need_credit_card_data": false,
"is_need_cvc": false,
"type": "deposit",
"vat_data": {
"included": false,
"applied": false,
"amount": "0.00",
"currency_code": "USD",
"value": "0.00"
},
"tax_data": {
"taxes": [
{
"name": "city_tax",
"included_by_supplier": false,
"amount": "748.08",
"currency_code": "HNL"
},
{
"name": "electricity_fee",
"included_by_supplier": true,
"amount": "0.06",
"currency_code": "USD"
},
{
"name": "service_fee",
"included_by_supplier": false,
"amount": "4.84",
"currency_code": "HNL"
},
{
"name": "vat",
"included_by_supplier": false,
"amount": "337.47",
"currency_code": "HNL"
}
]
},
"perks": {},
"commission_info": {
"show": {
"amount_gross": "2.00",
"amount_net": "2.00",
"amount_commission": "0.00"
},
"charge": {
"amount_gross": "1.00",
"amount_net": "1.00",
"amount_commission": "0.00"
}
},
"cancellation_penalties": {
"policies": [
{
"start_at": null,
"end_at": "2025-01-01T20:00:00",
"amount_charge": "0.00",
"amount_show": "0.00",
"commission_info": {
"show": {
"amount_gross": "0.00",
"amount_net": "0.00",
"amount_commission": "0.00"
},
"charge": {
"amount_gross": "0.00",
"amount_net": "0.00",
"amount_commission": "0.00"
}
}
},
{
"start_at": "2025-01-01T20:00:00",
"end_at": null,
"amount_charge": "1.00",
"amount_show": "2.00",
"commission_info": {
"show": {
"amount_gross": "2.00",
"amount_net": "2.00",
"amount_commission": "0.00"
},
"charge": {
"amount_gross": "1.00",
"amount_net": "1.00",
"amount_commission": "0.00"
}
}
}
],
"free_cancellation_before": "2025-01-01T20:00:00"
},
"recommended_price": null
}
]
},
"rg_ext": {
"class": 8,
"quality": 0,
"sex": 0,
"bathroom": 2,
"bedding": 0,
"family": 0,
"capacity": 0,
"club": 0,
"bedrooms": 6,
"balcony": 0,
"view": 0,
"floor": 0
},
"legal_info": {
"hotel": {
"name": "",
"address": "",
"taxpayer_number": "0000000000",
"state_registration_number": "0000000000000",
"work_time": "from 9-18 local time"
},
"provider": {
"name": "",
"address": "",
"taxpayer_number": "0000000000",
"state_registration_number": "0000000000000"
}
},
"room_name": "6 Bedrooms Villa",
"room_name_info": null,
"serp_filters": [
"has_bathroom",
"has_breakfast",
"has_internet"
],
"sell_price_limits": null,
"allotment": 9,
"amenities_data": [
"6-bedrooms",
"non-smoking"
],
"any_residency": true,
"deposit": null,
"no_show": {
"amount": "1.00",
"currency_code": "USD",
"from_time": "12:00:00"
},
"room_data_trans": {
"main_room_type": "6 Bedrooms Villa",
"main_name": "6 Bedrooms Villa",
"bathroom": null,
"bedding_type": null,
"misc_room_type": null
}
}
]
}
],
"changes": {
"price_changed": false
}
},
"debug": {
"request": {
"hash": "h-154bd176-8db0-5fbd-b169-1df3b43d1fc0",
"price_increase_percent": 20
},
"key_id": 1234,
"validation_error": null
},
"status": "ok",
"error": null
}
Errors
The error
field has the value specified in the headers below.
no_available_rates
The rate with the price_increase_percent
field value isn’t found. Try to change the value.
rate_not_found
The rate with the hash field value isn’t found. Too much time has probably passed since the search request. Send another search request.
invalid_params
- The
hash
field is required. - The
hash
field value is incorrect. - The
price_increase_percent
field value is less than0
.
unknown
The internal ETG services’ timeout.
prebook_disabled
There is no permission to use this call for this contract. Contact the API support team.
contract_mismatch
The pre-book contract differs from the rate contract. They should be the same.