/booking_submit_v7

Booking submit requests are sent by adding /booking_submit to your endpoint and sending the paramaters explained below in a POST request.
 
When the traveler has made a room choice after viewing the booking availability results, they proceed to the next step of making a room booking. They are presented with a booking form, where they fill in the details that are sent to the endpoint as part of the booking submit request.
 
(Note: The details shown in the following sample image are subject to change)
 

Request

https://partner-site.com/api_implementation/booking_submit

ContentType: application/json

{
    "checkin_date":"2016-10-28",
    "checkout_date":"2016-10-29",
    "partner_hotel_code":"sfssc1",
    "reference_id":"766588a634734cc8b60dd6a66b2561c4",
    "ip_address":"192.168.1.1",
    "customer":{
        "first_name":"Paul",
        "last_name":"Revere",
        "phone_number":"5555555555",
        "email":"paul.revere@tripadvisor.com",
        "country":"US"
    },
    "rooms":[{
            "party":{"adults":1,"children":[]},
        "traveler_first_name":"Paul",
        "traveler_last_name":"Revere"
    }],
    "special_requests":"A pre-made pillow fort and Vanilla coke on arrival please.",
    "payment_method":{
        "card_type":"Visa",
        "card_number":"5454545454545454",
        "cardholder_name":"Paul Revere",
        "expiration_month":"01",
        "expiration_year":"2015",
        "cvv":"999",
        "billing_address":{
            "address1":"141 Needham Street",
            "city":"newton",
            "state":"MA",
            "postal_code":"77777",
            "country":"US"
        }
    },
        "final_price_at_booking":{
        "amount":100,
        "currency":"USD"
    },
    "final_price_at_checkout":{
        "amount":200,
        "currency":"USD"
    },
    "partner_data":{
        "hotel_code":"sfssc1",
        "room_code":"FENWAY",
        "rate":1
    }
}

Properties

Field Type Description
checkin_date string
The check-in date of the traveler. The date will be in the form YYYY-MM-DD.
checkout_date string
The check-out date of the traveler. The date will be in the form YYYY-MM-DD.
partner_hotel_code string
Partner hotel id.
ip_address string
[Optional] Sending IP address.
reference_id string
TripAdvisor identifier for the booking session. Please note, this id may not be unique and should not be stored as a TripAdvisor “confirmation” id.
customer Customer The user booking the reservation.
rooms RoomStay array
An array of rooms to be booked.
special_requests [NEW] string
[Optional] Free text special requests or comments from the traveler to the hotel. This field will not be enabled in the UI until TripAdvisor has verified the implementation is working correctly.
payment_method PaymentMethod
An object containing the credit card details for payment of the reservation.
final_price_at_booking Price
An object containing the entire price to be paid at time of booking, including taxes and fees. This will be used to validate the line items.
final_price_at_checkout Price
An object containing the entire price to be paid at time of stay, including taxes and fees. This will be used to validate the line items. If the full price is paid at the time of booking, this element must still be included, with an amount of 0 or 0.00.
partner_data number, string or object

This data will not be interpreted by TripAdvisor, but will be sent back to the partner as-is when we attempt a booking. For example, this field might be used to store a partner 'rate key,’ ‘room key,’ and/or ‘product key.’ It can consist of arbitrary nested JSON, or a single string or number.

 

Response

ContentType: application/json

{
  "reference_id": "766588a634734cc8b60dd6a66b2561c4",
  "status": "Success",
  "reservation": {
    "reservation_id": "AB0005",
    "partner_hotel_code":"sfssc1", 
    "status": "Booked",
    "confirmation_url": "http://www.tripadvisor.com",
    "checkin_date": "2016-10-28",
    "checkout_date": "2016-10-29",
    "hotel": {
      "name": "Hotel Commonwealth",
      "address1": "500 Commonwealth Avenue",
      "city": "Boston",
      "state": "MA",
      "postal_code": "02215",
      "country": "USA",
      "latitude": 42.348808,
      "longitude": -71.094971,
      "phone": "555-555-5555",
      "url": "http://www.partner-site.com/hotelcommonwealth",
      "amenities": [
        "RESTAURANT",
        "NON_SMOKING"
      ],
      "photos": [{"url": "https://www.partner-site.com/images/hotel_1.jpg"}],
      "checkinout_policy": "Once you checkin you can\u0027t checkout"
    },
    "customer": {
      "first_name": "Paul",
      "last_name": "Revere",
      "phone_number": "5555555555",
      "email": "paul.revere@tripadvisor.com",
      "country": "US"
    },
    "rooms": [
      {
        "party": {
          "adults": 1,
          "children": []
        },
        "traveler_first_name": "Paul",
        "traveler_last_name": "Revere"
      }
    ],
    "legal_text": "Hotel Commonwealth is committed to privacy for everyone who accesses our website. This site, Hotel Commonwealth.com, only collects personal data about you as needed to provide you with outstanding service, and to help process your request or provide you with information.",
    "comments": "But only if you are of age.",
    "receipt": {
      "line_items": [
        {
          "price": {
            "amount": 100,
            "currency": "USD"
          },
          "type": "rate",
          "paid_at_checkout": false,
          "description": "base fee: day 0"
        },
        {
          "price": {
            "amount": 200,
            "currency": "USD"
          },
          "type": "fee",
          "paid_at_checkout": true,
          "description": "mint: day 0"
        }
      ],
      "final_price_at_booking": {
        "amount": 100,
        "currency": "USD"
      },
      "final_price_at_checkout": {
        "amount": 200,
        "currency": "USD"
      }
    }
  },
  "customer_support": {
    "phone_numbers": [{
       "contact": "555-555-5555",
       "description": "Support phone line"
    }]
  }
}

Properties

Field Type Description
problems Problem array
An array of problems that occurred
  • [Required] if status = "Failure."
  • [Optional] if status = "Success"
reference_id string
Echo the reference_id requested by TripAdvisor in the request. If the request fails (timeout or otherwise), TripAdvisor should be able to use this id in a booking_verify request to determine if the call were successful or not.
status string
An overall status of the booking request. One of the following:
 
  • Success
  • Failure
reservation Reservation
An object containing details associated with the reservation (receipt, date of stay, guests, etc.). Returned only if the booking is successfully made.
customer_support CustomerSupport  

A required object containing the hotel’s customer support contact information for guests.

This must be returned on both successes and failures.

 

API Objects

PaymentMethod

Request object describing the payment method of the booking.

Field

 Type Description
card_type string
The type of credit card used. Must be one of the following:
 
  • Visa
  • MasterCard
  • AmericanExpress
  • Discover
TripAdvisor requires a credit card at time of booking not only to support a hotel’s guarantee policy but also to reduce fraud. In the case where a hotel does not require a credit card guarantee, it will be up to the partner to either pass or not pass the credit card details to the hotel.
card_number string
The credit card number.
cardholder_name string
The name on the credit card.
expiration_month string
The expiration month as a two-digit string (e.g. 01, 02, .. 12)
expiration_year string
The expiration year as four digit string.
cvv string
The cvv number.
billing_address Address object
The billing address of the card.

Address

Field Type Description
address1 string
Street address
address2 string
[Optional] Additional address information
city string
Town or city
state string

State or province

State is required for all addresses from the United States (US), Australia (AU), Canada (CA), Malaysia (MY), Philippines (PH) and Italy (IT).

For addresses from the United Kingdom (GB), New Zealand (NZ), Ireland (IE), Singapore (SG), South Africa (ZA), France (FR) and others the state is optional.
postal_code string
U.S. Address: Required
Other Address: Optional
 
Zip code or postal code
country string
ISO 3166 country code

Reservation

Field Type Description
reservation_id string
Unique partner identifier for the reservation.
status string
The status of the reservation, must be one of:
 
  • Booked
  • Cancelled
  • CheckedIn
  • CheckedOut
confirmation_url string
Deep link to the reservation confirmation page.

 

The confirmation URL is displayed to the traveler after a booking has been confirmed. In addition, it is also displayed in the "My Bookings" page of the TripAdvisor account for the traveler.

 

Because this URL is displayed to the traveler, it therefore must be a link to a page owned by the booked property which:
1. displays any relevant confirmation codes, and,
2. confirms the dates, rooms and final price for the booking.
 

 

Example:
"confirmation_url": "http://bookings.bookingengine.com/Channels/BestHotel/confirm.jsp?mode=show&bid=8507809&bCode=9914&lang=en&currency=USD"
checkin_date string
The check-in date of the traveler. The date will be in the form YYYY-MM-DD.
checkout_date string
The check-out date of the traveler. The date will be in the form YYYY-MM-DD.
partner_hotel_code string
The partner specific code for this hotel. In a /booking_submit request this should be the same as in the request.
hotel HotelDetails object
An object containing information about the hotel booked.
customer Customer object
An object containing the customer booking the reservation.
rooms RoomStay array
An array of RoomStay objects.
legal_text string
Optional. Text describing any legal requirements for the hotel. If a partner has a single policy across all bookings, return the partner's legal text here. For example: Terms of Service and Privacy Policy.
comments string
Optional. Generic reservation comments field.
receipt Receipt object
Pricing information on the reservation.

Receipt

Field Type Description
line_items LineItem array
An array containing line items detailing each charge. An array of LineItem objects will contain a separate LineItem for each of rate, tax, and fee types.
final_price_at_booking Price object
An object containing the entire price to be paid at time of booking, including taxes and fees. This will be used to validate the line items.
final_price_at_checkout Price object
An object containing the entire price to be paid at time of stay, including taxes and fees. This will be used to validate the line items. If the full price is paid at the time of booking, this element must still be included, with an amount of 0 or 0.00.

Problem

Response object that is optional for a successful booking but required when there is an issue with the booking.

Field Required Type Description Example
problem
Required
 string One of the supported problem types. 
"problem" : "MissingEmail"
explanation Required string Partner-specific message to be displayed to the user providing details of the problem, and should be in the language of the 'lang' parameter of the request. 
"explanation" : "The e-mail
address is missing"
detail Optional string Partner-specific message providing details of the problem that will not be displayed to the user. Intended for logging purposes. 
"detail" : "E-mail address
missing"

Problem Types

Here is the list of problem types that TripAdvisor supports:

  • CreditCardDeclined
  • CreditCardTypeNotSupported
  • MissingTravelerFirstName
  • MissingTravelerLastName
  • MissingEmail
  • MissingReservationFirstName
  • MissingReservationLastName
  • MissingWorkPhone
  • MissingHomePhone
  • MissingAddress
  • MissingCity
  • MissingStateProvince
  • MissingCountry
  • MissingPostalCode
  • MissingCardholderName
  • InvalidTravelerFirstName
  • InvalidTravelerLastName
  • InvalidEmail
  • InvalidReservationFirstName
  • InvalidReservationLastName
  • InvalidWorkPhone
  • InvalidHomePhone
  • InvalidAddress
  • InvalidCity
  • InvalidStateProvince
  • InvalidCountry
  • InvalidPostalCode
  • InvalidCardholderName
  • UnknownUserProblem
  • RoomNotAvailable
  • PartnerDown
  • PartnerTimeout
  • PendingSupplier
  • AgentAttention
  • PropertyNotSupported
  • PriceMismatch
  • UnknownReference
  • UnknownPartnerProblem

Example

This table illustrates different problem situations and how they map to the listed Problem Types.

Example Problem Type Note
Missing required values:
first_name MissingTravelerFirstName  
last_name MissingTravelerLastName  
card_type CreditCardDeclined The explanation field must note this value is missing.
card_number CreditCardDeclined The explanation field must note this value is missing.
expiration_month CreditCardDeclined The explanation field must note this value is missing.
expiration_year CreditCardDeclined The explanation field must note this value is missing.
cvv CreditCardDeclined The explanation field must note this value is missing.
country MissingCountry  
partner_data UnknownReference The explanation field must note this value is missing.
Invalid values:
email InvalidEmail  
country InvalidCountry This applies if the country code is incorrect.
expiration_month CreditCardDeclined

The explanation field must note this value is invalid.

Note that the required format is 'MM', where the allowed range of values is for 'MM' is 01-12.
expiration_year CreditCardDeclined

The explanation field must note this value is invalid.

Note that the required format is '20YY', where the allowed range of values is from the current year to 2099.

(expiration_month && 

expiration_year) < Today

 CreditCardDeclined

The explanation field must note this value is invalid.

The date represented by the combination of Expiry Month and Expiry Year must not be in the past.
card_number CreditCardDeclined

The explanation field must note this value is invalid.

The credit card number must pass the Luhn algorithm.
cvv CreditCardDeclined

The explanation field must note this value is invalid.

For AmEx the CVV is a four digit number. For Visa, MasterCard, and Discovery the CVV is a three digit number. No alphabetic characters or other symbols allowed.
partner_hotel_code UnknownReference

The explanation field must note this value is invalid.
reservation_id UnknownReference The explanation field must note this value is invalid.
Incorrect Data Types:
phone_number InvalidHomePhone The phone number must be sent as a string containing the allowed characters for phone numbers.
card_number CreditCardDeclined This value must be a string containing digits only.
expiration_month CreditCardDeclined This value must be a string containing two digits.
expiration_year CreditCardDeclined This value must be a string containing four digits.
cvv CreditCardDeclined This value must be a string containing four digits if the value of "card_type" is "AmericanExpress". It must be three digits if the value of "card_type" is "Visa","MasterCard", or "Discover".