• Home

/booking_availability_v7

Booking availability requests are sent by adding /booking_availability to your endpoint and sending the parameters explained below in a POST request. 

 

When the booking availability results are returned, they are presented to the traveler beside the original hotel availability results. The traveler can then proceed to the next step of making a room booking.

 

(Note: The details shown in the following sample image are subject to change)

 

 

 

Please note that TripAdvisor will always expect a response with "api_version": 7 in it, with the respective fields required in a v7 response. In order to transition from our current v5 to v7 (new) API, TripAdvisor may send you a request with the "api_version": 5 and transition these to "api_version": 7 in the near future. Please ensure that your v7 endpoint accepts the TripAdvisor request with variant "api_version" (both 5 and 7).

Request

http://partner-site.com/api_implementation/booking_availability

ContentType: application/x-www-form-urlencoded

api_version=7
&hotel={
  "ta_id": 97497, 
  "partner_hotel_code": "sfssc1",
  "partner_url": "http://www.partner-site.com/hotelcommonwealth"
}
&start_date=2016-03-21
&end_date=2016-03-23
&party=[{"adults":2}]
&lang=en_US
&currency=USD
&user_country=US
&device_type=d
&query_key=6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2
&booking_session_id=c575ec5ae3c84294bf67c1b05590b3c2
&booking_request_id=CSI-xkundqpe4nfrtem2ypq2ygjfde 

Parameters

Name	Type	Description
api_version	number	The version of the API that this request is using.
hotel	object	JSON serializable hash representing requested hotel.  key description type ta_id TripAdvisor hotel IDs integer partner_hotel_code Partner hotel ID string partner_url Deeplink for this property. string Example: hotel={"ta_id": 1128635, "partner_hotel_code": "1191", "partner_url": "http://partner.com/deeplink/to/1191"} Note: All your availability lookups must use your partner_hotel_code. The TripAdvisor ID can change as the site changes. The partner_url is mostly used for internal purposes. Partners implementing the API may ignore this parameter.
start_date	string	The check-in date of the traveler. The date will be in the form YYYY-MM-DD.
end_date	string	The check-out date of the traveler. The date will be in the form YYYY-MM-DD.
party	array	Array of JSON objects representing number of adults and children traveling.  key description type adults The number of adults staying in the room. integer children [Optional] The ages of any children staying in the room. integer array Each Party object represents a request for a separate room. For example, "party":[{“adults": 2}] is a request for 1 room that accommodates 2 adults, or "party":[{"adults": 3},{"adults": 2, "children": [9,5]}] is a request for 1 room for 3 adults and 1 room for 2 adults and 2 children for a total of 2 rooms.
lang	string	Language code (see Supported Languages). The language that TripAdvisor would prefer that the partner return with. If the partner does not have the language of the request, they can return a less specific language. e.g. If the request is asking for de_AT, then the response can be de. If the partner does not have the language specified by lang, they will not show up in Instant Booking.
query_key	string	String useful for debugging. It is recommended for this value to be logged.
currency	string	[Not always present] ISO 4217 currency code. All prices, taxes, fees, and discount amounts should be returned in this requested currency. If this is not possible, the currency should match the one seen by a user from the given user_country if present (see below). If the currency the user will be charged in differs to the requested currency, always send the currency of charge. For example TripAdvisor requests USD but hotel is based in UK and charges in GBP, in that instance send GBP, currency conversion will be handled by TripAdvisor.
user_country	string	[Not always present] ISO 3166-1 alpha-2 country code corresponding to the user making this request. If present, local taxes and fees must be included and the currency must match the one seen by a user from this country visiting your website. If this is not possible, return the local currency of the hotel. This parameter is required to be supported if pricing differs based on the country where the user makes the request.
device_type	string	[Not always present] Identifies the user’s device type. Takes values “d”, “m” or “t” corresponding to DESKTOP, MOBILE, or TABLET, respectively. This value is required if pricing differs by device type.
booking_session_id	string	[Not always present] The booking_session_id is primarily used for internal purposes. Partners implementing the API may ignore this parameter.
booking_request_id	string	[Not always present] The booking_request_id is primarily used for internal purposes. Partners implementing the API may ignore this parameter.

Response

ContentType: application/json

{
    "api_version": 7,
    "hotel_id": 730099,
    "start_date": "2016-03-21",
    "end_date": "2016-03-23",
    "party": [
        {
            "adults": 2
        }
    ],
    "lang": "en_US",
    "query_key": "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
    "user_country": "US",
    "device_type": "d",
    "hotel_room_types": {
        "king1": {
            "code": "king1",
            "name": "Deluxe King Room",
            "description": "Plush King bed, deluxe beddings, recently renovated bathroom, smoking permitted",
            "photos": [
                {
                    "url": "https://www.partnersite.com/FenwayRoomBed.jpg",
                    "width": 200,
                    "height": 300,
                    "caption": "Image of King Bed"
                }
            ],
            "room_amenities": {
                "standard": [
                    20,
                    900118
                ],
                "custom": [
                    "My custom chair",
                    "Wolf appliances"
                ]
            },
            "room_size_value": 500,
            "room_size_units": "square_feet",
            "bed_configurations": [
               [{
                 "type": "standard",
                 "code": 3,
                 "count": 1
                 },
                 {
                  "type": "custom",
                  "name": "Loft",
                  "count": 1
                 }]
            ],
            "room_view_type": {
                "standard": [
                    10
                ],
                "custom": [
                    "Northern Lights"
                ]
            },
            "accessibility_features": {
                "standard": [
                    900501, 900505
                ],
                "custom": [
                ]
            },
            "max_occupancy": {
                "number_of_adults": 2,
                "number_of_children": 0
            },
            "room_smoking_policy": "smoking"
        },
        "king2": {
            "code": "king2",
            "name": "Deluxe King Room - Non Smoking",
            "description": "Plush King bed, deluxe beddings, recently renovated bathroom",
            "photos": [
                {
                    "url": "https://www.partnersite.com/FenwayRoomBed.jpg",
                    "width": 200,
                    "height": 300,
                    "caption": "Image of King Bed"
                }
            ],
            "room_amenities": {
                "standard": [
                    20,
                    101,
                    900118
                ],
                "custom": [
                    "My custom chair",
                    "Wolf appliances"
                ]
            },
            "room_size_value": 400,
            "room_size_units": "square_feet",
            "bed_configurations": [
               [{
                 "type": "standard",
                 "code": 3,
                 "count": 1
                 }],
               [{
                  "type": "standard",
                  "code": 5,
                  "count": 2
                 }]
             ],
            "extra_bed_configurations": [
               [{
                 "type": "standard",
                 "code": 4,
                 "count": 1
                 },
                 {
                  "type": "custom",
                  "name": "Rollaway with wheel locks and adjustable height",
                  "count": 1
                 }]
            ],
            "room_view_type": {
                "standard": [
                    10
                ],
                "custom": [
                    "Northern Lights"
                ]
            },
            "accessibility_features": {
                "standard": [
                    900504
                ],
                "custom": [
                ]
            },
            "max_occupancy": {
                "number_of_adults": 2,
                "number_of_children": 2
            },
            "room_smoking_policy": "non_smoking"
        }
    },
    "hotel_rate_plans": {
        "bar": {
            "name": "Best Available Rate",
            "code": "bar",
            "description": "Best available rate available in March, suitable for family stays under 7 days",
            "photos": [
                {
                    "url": "https://www.partnersite.com/Jetski_kayak.jpg",
                    "width": 200,
                    "height": 300,
                    "caption": "Image of rate amenities"
                }
            ],
            "rate_amenities": {
                "standard": [
                    75
                ],
                "custom": [
                    "Complimentary jetskis",
                    "Kayak rentals"
                ]
            },
            "cancellation_rules": {
                "deadline": "2016-03-17T16:00:00",
                "penalty_exists": true,
                "policy_info": "Partially refundable rate",
                "fees": [
                    {
                        "currency": "USD",
                        "amount_type": "numNights",
                        "amount": 2,
                        "tax_inclusive": true,
                        "days_before_arrival": 2
                    },
                    {
                        "currency": "USD",
                        "amount_type": "fixed",
                        "amount": 50,
                        "tax_inclusive": true
                        "days_before_arrival": 4
                    }
                ]
            },
            "meal_plan": {
                "standard": [
                    22
                ],
                "custom": [
                    "Brunch on weekend mornings"
                ]
            },
            "discount_type": {
                "standard": [
                    5
                ],
                "custom": []
            }
        },
        "online": {
            "name": "Online Discount",
            "code": "online",
            "description": "Exclusive, non-refundable rate for online reservations",
            "photos": [
                {
                    "url": "https://www.partnersite.com/NFL_cable.jpg",
                    "width": 200,
                    "height": 300,
                    "caption": "Image of cable TV selection"
                }
            ],
            "rate_amenities": {
                "standard": [
                    207
                ],
                "custom": [
                    "NFL Network"
                ]
            },
            "refundable": "none",
            "cancellation_rules": {
                "penalty_exists": true,
                "policy_info": "Non-refundable rate. No cancellations permitted, all taxes and fees will need to be paid.",
                "fees": [
                    {
                        "currency": "USD",
                        "amount_type": "percent",
                        "amount": 100,
                        "tax_inclusive": true
                    }
                ]
            },
            "meal_plan": {
                "standard": [
                    22
                ],
                "custom": [
                    "Brunch on weekend mornings"
                ]
            },
            "discount_type": {
                "standard": [
                    9
                ],
                "custom": [
                    "Online Discount"
                ]
            }
        }
    },
    "hotel_room_rates": [
        {
            "final_price_at_booking": {
                "amount": 240,
                "currency": "USD"
            },
            "final_price_at_checkout": {
                "amount": 0,
                "currency": "USD"
            },
            "hotel_room_type_code": "king1",
            "hotel_rate_plan_code": "bar",
            "partner_data": {
               "myhotel_code": "sfssc1",
               "myroom_code": "FENWAY",
               "rate_hotel_info": 1
            },
            "line_items": [
                {
                    "price": {
                        "amount": 220,
                        "currency": "USD"
                    },
                    "type": "rate",
                    "paid_at_checkout": false,
                    "description": "This is the base rate."
                },
                {
                    "price": {
                        "amount": 20,
                        "currency": "USD"
                    },
                    "type": "tax",
                    "paid_at_checkout": false,
                    "description": "This is a tax."
                }
            ],
            "payment_policy": "Valid ID with proof of payment required at check in",
            "rooms_remaining": 2
        },
        {
            "final_price_at_booking": {
                "amount": 220,
                "currency": "USD"
            },
            "final_price_at_checkout": {
                "amount": 0,
                "currency": "USD"
            },
            "hotel_room_type_code": "king1",
            "hotel_rate_plan_code": "online",
            "description": "",
            "partner_data": {
               "myhotel_code": "sfssc1",
               "myroom_code": "FENWAY_KNG",
               "rate_hotel_info": 2
            },
            "line_items": [
                {
                    "price": {
                        "amount": 200,
                        "currency": "USD"
                    },
                    "type": "rate",
                    "paid_at_checkout": false,
                    "description": "This is the base rate."
                },
                {
                    "price": {
                        "amount": 20,
                        "currency": "USD"
                    },
                    "type": "tax",
                    "paid_at_checkout": false,
                    "description": "This is a tax."
                }
            ],
            "payment_policy": "Valid ID with proof of payment required at check in",
            "rooms_remaining": 1
        },
        {
            "final_price_at_booking": {
                "amount": 200,
                "currency": "USD"
            },
            "final_price_at_checkout": {
                "amount": 0,
                "currency": "USD"
            },
            "hotel_room_type_code": "king2",
            "hotel_rate_plan_code": "bar",
            "description": "",
            "partner_data": {
               "myhotel_code": "sfssc1",
               "myroom_code": "FENWAY_KNG",
               "rate_hotel_info": 3
            },
            "line_items": [
                {
                    "price": {
                        "amount": 180,
                        "currency": "USD"
                    },
                    "type": "rate",
                    "paid_at_checkout": false,
                    "description": "This is the base rate."
                },
                {
                    "price": {
                        "amount": 20,
                        "currency": "USD"
                    },
                    "type": "tax",
                    "paid_at_checkout": false,
                    "description": "This is a tax."
                }
            ],
            "payment_policy": "Valid ID with proof of payment required at check in",
            "rooms_remaining": 5
        },
        {
            "final_price_at_booking": {
                "amount": 180,
                "currency": "USD"
            },
            "final_price_at_checkout": {
                "amount": 0,
                "currency": "USD"
            },
            "hotel_room_type_code": "king2",
            "hotel_rate_plan_code": "online",
            "description": "",
            "partner_data": {
               "myhotel_code": "sfssc1",
               "myroom_code": "FENWAY_KNG2",
               "rate_hotel_info": 4
            },
            "line_items": [
                {
                    "price": {
                        "amount": 160,
                        "currency": "USD"
                    },
                    "type": "rate",
                    "paid_at_checkout": false,
                    "description": "This is the base rate."
                },
                {
                    "price": {
                        "amount": 20,
                        "currency": "USD"
                    },
                    "type": "tax",
                    "paid_at_checkout": false,
                    "description": "This is a tax."
                }
            ],
            "payment_policy": "Valid ID with proof of payment required at check in",
            "rooms_remaining": 3
        }
    ],
    "hotel_details": {
        "name": "Hotel Commonwealth",
        "address1": "500 Commonwealth Avenue",
        "address2": "",
        "city": "Boston",
        "state": "Massachusetts",
        "postal_code": "02492",
        "phone": "8001234567",
        "checkinout_policy": "For early check in, please contact hotel.",
        "checkin_time": "12:00",
        "checkout_time": "14:00",
        "hotel_smoking_policy": {
            "standard": [
                47
            ],
            "custom": [
                "Strict non smoking policy"
            ]
        },
        "pet_policy": {
            "standard": [
                6
            ],
            "custom": [
                "My own pet policy if applicable"
            ]
        },
        "child_policy": "All children are welcome",
        "parking_shuttle": {
            "standard": [
                185
            ],
            "custom": [
                "You can park on curbside in a metered spot"
            ]
        },
        "extra_bed_policy_hotel": "Rollaway beds and cribs available on request",
        "hotel_amenities": {
            "standard": [
                5,
                15
            ],
            "custom": [
                "Bean bag chairs"
            ]
        },
        "photos": [
            {
                "url": "https://www.partnersite.com/hotel_lobby.png",
                "width": 200,
                "height": 300,
                "caption": "Hotel Lobby"
            },
            {
                "url": "https://www.partnersite.com/hotel_cafe.png",
                "width": 200,
                "height": 300,
                "caption": "Hotel Cafe"
            }
        ],
        "extra_fields": [
            {
                "id": "text1",
                "description": "Enter text",
                "required": false,
                "type": "text",
                "default_value": "foo"
            },
            {
                "id": "select2",
                "description": "Choose an option",
                "required": true,
                "type": "single_select",
                "field_values": [
                    {
                        "id": "first",
                        "description": "First option"
                    },
                    {
                        "id": "second",
                        "description": "Second option"
                    }
                ]
            }
        ]
    },
    "accepted_credit_cards": [
        "Visa",
        "MasterCard",
        "AmericanExpress"
    ],
    "customer_support": {
        "phone_numbers": [
            {
                "contact": "555-555-5555",
                "description": "Support phone line"
            }
        ]
    },
    "terms_and_conditions": "Terms and conditions text",
    "terms_and_conditions_url": "http://www.example.com/terms_and_conditions",
    "payment_policy": "Payment policy partner text - use this field for payment policies that apply to the entire hotel",
    "other_policy": "Other policy partner text"
}

           
           "bed_configurations": [
               [{
                 "type": "standard",
                 "code": 3,
                 "count": 1
                 },
                 {
                  "type": "custom",
                  "name": "Loft",
                  "count": 1
                 }]
            ]

            "bed_configurations": [
               [{
                 "type": "standard",
                 "code": 3,
                 "count": 1
                 }],
               [{
                  "type": "standard",
                  "code": 1,
                  "count": 2
                 }]
             ]

            "bed_configurations": [
               [{
                 "type": "standard",
                 "code": 3,
                 "count": 1
                 }],
               [{
                  "type": "standard",
                  "code": 1,
                  "count": 2
                 }]
             ],

            "extra_bed_configurations": [
               [{
                 "type": "standard",
                 "code": 900302,
                 "count": 1
                 },
                 {
                  "type": "custom",
                  "name": "Rollaway with wheel locks and adjustable height",
                  "count": 1
                 }]
             ]

In summary, to build the "line_items" correctly the value of the final price for a property must be obtained first, then how much of it is taxes and fees must be determined.  Once these three figures are found, the breakdown on how much of each is to be paid at booking and how much is to be paid at checkout needs to be clarified.

Example calculation:

"line_items": [
 {
    "price": { "amount": 425.28, "currency": "USD" },
    "type": "rate",
    "description": "Rate",
    "paid_at_checkout": false
 },
 {
    "price": { "amount": 50.65, "currency": "USD" },
    "type": "tax",
    "description": "Tax",
    "paid_at_checkout": false
 },
 {
    "price": { "amount": 124.14, "currency": "USD" },
    "type": "rate",
    "description": "Rate",
    "paid_at_checkout": true
 },
 {
    "price": { "amount": 24.85, "currency": "USD" },
    "type": "tax",
    "description": "Tax",
    "paid_at_checkout": true
 }]

The total price at booking is the sum of everything that has the "paid_at_checkout" flag set to "false", and the total price at checkout is the sum of everything with flag set to "true".

At booking the guest would pay 425.28 + 50.65.

At checkout they would pay 124.14 + 24.85.

Example: Multiple Rooms

"errors": [
    {
        "error_code": 3,
        "message": "Hotel code 114134 is no longer used.",
        "hotel_ids": [
            114134
        ]
    }
]

line_items: [
  {
    "price": {
        "amount": 75,
        "currency": "EUR"
    },
    "type": "rate",
    "paid_at_checkout": true,
    "description": "Base price"
  },
  {
    "price": {
        "amount": 5,
        "currency": "EUR"
    },
    "type": "fee",
    "paid_at_checkout": false,
    "description": "Resort fee"
  },
  {
    "price": {
        "amount": 20,
        "currency": "EUR"
    },
    "type": "tax",
    "paid_at_checkout": false,
    "description": "Total tax amount"
  }
]