TripAuthority is Alliance Reservations Network API for hotel availability, rate details, bookings, and cancellations. This guide provides the information a competent developer will need in order to integrate our services with your website. XML integration is for serious businesses only; it will require major development and is not suitable for a part time developer or first time developer attempting to learn on the job. We charge a $50,000 integration fee before you're allowed access to the API to begin development.
API Credentials If you're ready to begin, first register as an affiliate. Once you have your account, email our accounting department and inform them you'd like to pay the fee and begin development. You will be given separate credentials for the API in addition to the credentials you received for being an affiliate. After you receive your API credentials, the information found below will enable your developer to code to our API. Your account with initially be in test mode. While in test mode, responses will contain fake data that looks like complete nonsense but are fully functional and is intended to for your developer to program against. Using junk data ensure your programmer doesn't attempt to rely on discerning meaning from free text fields that contain no intentional meaning. Fields that matter have meaningful data like prices and gateways and taxes and fees and room and rate codes and fields that contain junk data are for display to your users. Things like room descriptions and rate descriptions are intended to be shown, not parsed and programmed against. The code you develop should work just as well on the junk data as on the real data you'll see later after live mode is enabled. Do not request access to live data until you've fully worked through the booking and cancellation process on the test drivers.
The required work-flow to use TripAuthority as the back end for you own booking engine requires the following steps. This is just an overview, details about the actual requests and valid values can be found in the XSD and the charts below.
Static Content and Searching First download our property data and set-up your own local database of all static content. You will be doing your own searching in your own database locally. Our API does not do hotel searches, that's your responsibility. You should automate the sync process as our data dumps are updated daily and you'll need to keep your local database relatively up to date. It is important that you do this so you have fresh content and access to the latest hotels and know which hotels are no longer active so you can disable them in your database. Once your engine has completed its search and you know what hotels you'd like to pull rate information for, you're ready for the next step.
Availability Request Given a list of hotels that you're interested in from your own local hotel search, you can now query TripAuthority for availability information for those hotels. Here's a sample request:
Make this request for the total number of rooms and the total number of guests. Request is limited to 50 hotels per request; make multiple requests if you need more than 50. You will get back a response that contains available rate plans and room types from various suppliers that we call gateways. 50 is the maximum, but not the best performing, use smaller batches to get faster responses. Experiment to find the right batch size for you.
Rate Results -- Nightly or First Night Only The response might contain full nightly rates and tax information, or possibly only first night rates with or without tax information. For gateway 4, the rate labelled FirstNightRate can either be the first night rate, the highest night rate, or the average nightly rate; most of the time it's the first night rate. We have no way of knowing which night of they stay they are showing us, so we just always call it FirstNightRate as that is the most common by far.
Display what you can to the guest. Full rate information are not always available and there is nothing you can do about this; this is how the industry works and you must accept this. To not show rates that don't include the full price of the stay you'd have to not sell well over half of the inventory available on the market today. Your application requirements do not matter, you must work with what is available on the Global Distribution System (GDS). There is no creative way around this restriction that doesn't cause excessive traffic and exceed our bandwidth restrictions or we'd have already done it.
The response should be essentially self documenting, however, DisplayCurrency requires a bit of explanation. Rates are always returned in the hotels native currency. If you request another DisplayCurrency, the correct conversion rate from the hotels native currency to the desired DisplayCurrency will be returned as DisplayCurrencyMultiplier. You may use this value to convert the hotel currency to the desired currency for display in your UI. This allows you to show both the original currency and display currency side by side without us duplicating the values in the XML.
Make sure your code can handle all cases and don't switch on the gateways doing different things for different gateways. Any gateway could potentially return any valid response with varying amounts of information. Your code should not be gateway specific. New gateways could be added at any time and you don't want your code to break because of that.
When an availability calls fails to return rates you just don't display rates for that hotel, nothing else needs to be done.
AvailabilityType Example Availability Call attributes:
New attribute AvailabilityType can either be "List" or "Detail". Not present is the same as specifying "List".
Only set to type "Detail" if user is on a property info page and multiple rates are needed for a single hotel. "List" type only returns the lowest priced rate for some suppliers.
Details Request Once the guest has selected a particular rate to view, you'll then be ready to use the information from the availability response to build and submit a detail request. Given the hotel, gateway, rate code, and room code, you can request all the details for a particular rate.
Also make this request for the total number of rooms and the total number of guests. The detail response contains the full information for that particular rate including full nightly rates, all taxes and fees associated with the room, and all hotel, payment, and cancellation policies that apply to the rate.
This is a much more expensive request, do not attempt to do a full details request for every rate that comes back in the availability response to try and get the full nightly rate and tax information up front. There's a reason this information isn't included in the availability response, it would be too much load on the suppliers systems. Accordingly, this request is rate limited to a few requests per second max and logged to inform us you're abusing the API; you will be denied with a 429 HTTP status code should you exceed the rate limit.
When a detail request fails it means the rate is no longer available, this is a common case and the user should be informed that this rate is sold out or other not available. Subsequent availability calls should no longer return this rate, the failed call should flush the availability cache to ensure the next call receives a fresh copy of current rates at the hotel.
Detail responses contain all the information a guest needs to make a purchase decision, make sure they see it all. All cancel fees and penalties, cancel policy, and in fact all policy nodes contain information the guest must see. Make sure your booking page displays all of this information.
Detail responses may contain information about extra adult fees, this is informational only, do not rely on this field for pricing as it is not always available and may simply come back with $0 amount. This doesn't mean there isn't a charge for additional guests, it just means we don't have the information. All room prices are based on the number of adults you request per room. Do not assume that you can request 1 adult and then book extra people into the room because the extra person fees are 0. If you do so you will be liable for the difference when the guest complains about having to pay extra when they arrive at the hotel.
Reservation Request Once the guest has decided to book a particular rate, and they've viewed all the relevant details, policies, and charges for that rate, you can use the information contained within the details response, combined with the information you collect from the user, to build a reservation request.
For collections and accounting reasons, and unlike the previous requests, this request must be made for a single room, with the number of guests that will be in this room. If you give us an incorrect number of adults and pricing is affected, you are liable for any refund due to the guest. This will require that you do a little math with the values from the detail request to determine the one room totals to submit a correct reservation request; alternatively you could do a details request for a single room which will return all the correct values necessary to build a successful booking request. Make one reservation request for each room you want to book, the system will reject any attempt to book more than one room in a single request.
The reservation response will contain three values you'll need: the reservation and itinerary id's which will be needed to cancel a reservation, and the confirmation number which you'll give to the guest. You must store all of these for later use in the cancellation request.
Reservation requests can fail for many reasons, most often because a rate is no longer available because of selling out, or because some hotel restriction on those particular dates has been violated such as no-checkin or no-checkout. Refer to the errors.csv for a list of failure codes and error messages we display to our users. You may use this or display errors of your own choosing.
Cancellation Request Should a guest need to cancel a reservation, you can submit a cancellation request.
If the request succeeds you'll receive a CancellationID indicating success. Should a cancellation be in conflict with the hotels cancellation policy, it will fail. If the request fails, you'll need to present the guest with whatever options for customer service you have to allow the issue to be resolved manually.
XML is not just a string XML documents are not just concatenated strings. Do not build requests by just sticking a bunch of strings together or you'll often end up with an invalid document that isn't properly XML encoded. Whatever language or library you're using, there is a proper XML Document object you should be using to build XML Documents which will properly handle the necessary XML encoding.
There are three methods you may use to submit requests to us: SubmitRequestDoc, SubmitRequestRpc, and SubmitRequest. This is also the order of preferred use. If you're using .Net or Java, you'll probably want to use SubmitRequestDoc. If you're using PHP, Python, or Ruby, you'll probably have less trouble with SubmitRequestRpc. As a last resort, if you're going to use SubmitRequest, you'll need to XML encode your xmlFormattedString to get SubmitRequest working since it takes the document as a formatted string. That means a request such as this...
Multiple Currencies When dealing with multiple currencies leave all currencies in their native rate. The rate that came down in the rate details call is the native rate. For booking fees, that's always USD. For the hotel's rate, that's whatever rate is native to that hotel. For your user, that is the display currency. You cannot change the currency to another currency and submit a reservation.
If you're showing the guest USD, and you get a rate from a Canadian hotel, then you use the DisplayCurrencyMultiplier that comes back on the room to convert the Canadian rate to USD *for display* to the user only. Behind the scenes, you're working with a Canadian rate and you need to submit a booking request using the Canadian rate for the room. Even with this Canadian rate, you'd have gotten a USD booking fee. You can't add different currencies, so you must convert them all to a single currency before doing the addition for the user. Since the users DisplayCurrency is USD, then multiply everything by its DisplayCurrencyMultiplier and then you'll have all USD prices so you can correctly summarize the total charges to the user.
When submitting a reservations, you're pretty much just echoing back what comes down in the detail response. Booking fees will always be in USD, regardless of what currency the native hotel rate is, because we charge the booking fee.
Developer Experience Make sure to choose a developer who has experience with cross platform SOAP web services. Be very careful before choosing a PHP developer who has never worked with a .Net SOAP web service before (it will cost you), they often fail to be able to complete an integration. They should have past experience calling .Net SOAP web services from the language the client is using. They should understand some basic things like document encoding, be it literal, RPC, or soap encoded, and should be good enough to shake out the kinks and get it working on their own. They should also know how to trace their requests and collect samples of both the request and the response before seeking advice from us. Do not send us your source code asking us to fix it for you (oddly typical of PHP developers), it is your responsibility to know how to use your language of choice and to understand the proper way to use web services.
Sample Code We do not provide sample code, these are simple web services and a competent developer should be able to reference and use this service successfully in under an hour without requiring that we write the code for him. If you require sample code to understand how to reference and use a simple web service, you are not experienced enough for this integration.
See our full list of supported gateways. Gateway 2 and 4 are pay at check-in, all other gateways are pay at time of booking. After you've integrated and disabled test mode, you will find you're authorized to see all Gateways (individual suppliers) except Gateway 2, 7. Gateway 7 is only available if you're building a private members only non-public site. Gateway 2 is for the delivery of negotiated and preferred rates from hoteliers to your account; until you've negotiated preferred rates, you won't see any.
To learn more about Gateway 2, email email@example.com and request Gateway 2 information.
Testing Test all requests in the live environment. By default your new account will be in test mode that will replace the live gateways and query results with fake test data that can be queried and booked using fake credit cards and absent any consequences. Test gateways are 28 and 29 and the room and rate descriptions for those test gateways will be obviously fake data gibberish; if you book a reservation on any other gateway, you are responsible for it as it is a real reservation with real charges and penalties.
You can use two fake card numbers to force credit card failures to ensure you handle them properly. 4321432143214327 will cause an authorization declined error and 5454545454545454 will cause an amount that must be charged is different from amount authorized error. 4111111111111111 can be used on the test gateways to book a successful reservation.
Upon request we will refund any booking fees that may have been charged during testing. For service fee credits, if any, email the cancellation acknowledgement to firstname.lastname@example.org with the subject line "Credit for Service Fee of TEST Reservation"
Support We have set-up support groups to help you quickly get in contact with the correct people to help you with your problem. We encourage you to only use these email addresses when requesting support, and to not send emails to individuals. Please do not ask us for phone calls and conference calls with your developers if you haven't attempted to solve the problem via email support. All problems can be solved through email support, we are very responsive.