Content Overview

General Best Practice

The following sections highlight the best practice methodologies that should be applied throughout your integration to get the most value from each of your EAN API request and responses to provide the best offering to your customer.


EAN uses a tiered support model, where requests are triaged and then moved to experts to help you out with your specific query.

Please remember to always open a separate request in order for us to respond with the best possible answer and allocate resources. Additionally, it is important that you use your corporate email address so we can recognise and link your account details.

Please have a look at our forum prior to sending a request:

Request Structure (REST & JSON)

Before focusing on individual calls it is important to find the right protocol for your API integration. The EAN API currently supports REST with injected XML and REST with JSON. The EAN preference is fully JSON.

Future iterations of the API will utilise JSON, engineering your integration to be able to deal with JSON will futureproof your design.

Common Attribute Usage

Attributes that are passed to the API provide vital information of what is being requested and what is returned. Some of these attributes affect the way in which EAN determine the pricing of hotels. EAN inventory has a very dynamic pricing model. The following attributes are used to determined the prices and availabilities that are returned.


  • Use this attribute to identify the origin of your request.
  • This is a requirement from the EAN operations department to identify traffic and how the API is being used. It helps us predict how traffic will evolve over time which leads to a much more stable service benefitting you and other EAN partners.


  • Insert your own unique value for each initial List call. This value will be echoed back in the List response and should be carried forward to the Avail Request. Again, take the echoed back value from the Avail response and use this in the Reservation Request.
  • This value should be passed from List to Availability and Reservation API calls.
  • By implementing this best practise, it will ensure that EAN can track the full end to end shop and book journey via our logging system and be able to investigate, troubleshoot and provide optimization recommendations quickly.


  • This should be the IP address of the customer and should geolocate back to the country of the customer’s location.
  • Please only send IPV4 addresses only e.g.
  • This field is also used for fraud recovery by EAN.
  • If you are unable to send the actual customerIpAddress, you should pass an IP address that will geolocate back to the customer’s country of residence, if known.


  • Identifies your customer’s country and the nationality of the Point of Sale used for booking. It will also determine the language returned in the response. See our supported locales.


  • This value is used to determine the currency in which you request a price. EAN supports a number of billable currencies. If a non-billable currency is requested the API will return the requested currency in the ConvertedRateInfo for display purposes. However the currency used to make the reservation should be take from the chargeableRateInfo node.

The API is designed to use a combination of the customerIpAddress, locale and currencyCode to allocate the correct pricing and availability profile. This ensures the accuracy of rates so that the appropriate rates are returned by the API to your customers.

Not sending any or inconsistent values for either of these 3 parameters will mean that the API will make an inaccurate judgement to determine the customer's location, and as a result, price and availability accuracy may be affected.


  • This is used to understand information about the customer's browser and operating system. This field is also used by the EAN API to provide Mobile Rate Promotions.


Signature Authentication

EAN's signature (sig) authentication method is required for all API requests with the value of sig being calculated by generating an MD5 hash made up of the API key, the API user’s shared secret, and a UNIX timestamp. When a signature is sent, our downstream services will attempt to regenerate the signature value to validate authenticity. If your sig is invalid, this will cause a failure and for security reasons block further attempts for a period of time.

Avoid the following points of failure for signature generation:

Out of sync timestamps

The EAN API accepts timestamps up to five minutes before or after the server timestamp to accommodate for reasonable clock drift. To avoid authentication failures, ensure that you:

  • Use GMT time, not local time.
  • Use seconds, not milliseconds. Some systems return the time in milliseconds by default.
  • If you're receiving authentication errors with sig requests, use the Server Info timestamp returned in the error message with your next request in order to sync your time with the server. E.g. <ServerInfo serverTime="19:11:13.082-0500" timestamp="1311725473" instance="48" />

Invalid signature lengths and characters

  • Always generate signature values of 32 lower-case characters in length
  • Enhance your signature generation code to add a leading 0 to the signature when detected to have 31 characters
  • Always provide the signature value in lower-case characters

Review our full signature authentication documentation on this page, including coded examples of preventing such errors:

EAN API Rate Types

There are four different rateType combinations to be aware of when shopping and booking with the EAN API. It is important to use the correct value for your Pre-Pay, Post-Pay and Package Rate requests.

Pre-Pay, Expedia Collect or StandAlone

This rate is paid for at the time of booking. Use rateType=‘MerchantStandard’.

Post-Pay, Hotel Collect or Direct Agency

The property collects payment directly from the customer. Use rateType=‘DirectAgency’.

Pre & Post Pay or Expedia Traveler Preference ‘ETP’

Both Pre- and Post-Pay rates will be returned in the response. The rateType for the customer's selected list result should be used in the Avail and Book requests. Use rateType=‘MerchantStandard|DirectAgency’.

Note: when dealing with ETP rates, the rateInfos object will potentially return an array of two separate rateInfo items (one for the Pre-Pay rate, and one for Post-Pay rate). Your integration should read and display both of these rates for the user to select and book accordingly.

Package Rates or Dynamic Package

This promotional rate should be packaged with a travel component in an opaque fashion (that is, the price of the accommodation should not be known to the end customer). Use rateType=‘MerchantPackage’.

Note: It is not possible to request Package rates together with any other rate. All rates returned by Package requests should be treated as Package regardless of the rateType displayed in the response. Where properties do not have Package rate availability, Merchant Standard rates will be returned. Again all rates should be treated as Merchant Package regardless of the rateType specified in the response.

Extensible Integration

The latest version of the EAN API should be integrated to be able to handle the addition of new elements without error. An extensible system is one whose internal structure and data flow are minimally or not affected by new or modified functionality. For example, recompiling or changing your original source code should be not be necessary when the EAN API returns new elements.


Subscribe to receive email updates about the EAN API and your account. Log in or register at, click the “Follow” button and choose “New Articles and Comments”.


Shopping, Content & Usage

The following sections cover the various ways of requesting EAN inventory from the API in the most effective ways.

Hotel Searching


Use this request to return list of hotels from a given geographical location or by passing a list of HotelIds to the API.


The most efficient approach for querying this request is to pass a list of HotelIds in the HotelIdList element. These HotelIds should be gathered from the EAN Static Content database files. This approach enables you to gather and customize what hotels you are searching for specific to your business needs. It also removes this step from the EAN API, which means results can be returned quicker.

Sorting and Filtering

The EAN default sort (no sort option specified in the request) is currently the most optimized sort. Results will be displayed in order of a mix of best conversion and highest revenue share. The first hotel will be the most relevant candidate out of the list of possible hotels based on many different factors, including the hotel's ranking, popularity, price, how often it is booked and dates selected.

Our recommendation is to let EAN handle the sort order for the initial hotel list results.

When sorting or filtering hotels on static values such as Name, Star Rating, Proximity, etc., please consider doing this with the EAN Static Content files instead of the EAN API for greater speed and less requests to the EAN API.


When using the List request, you cna use the numberOfResults attribute to specify the maximum number of hotels returned per request.

  • If you don’t pass this value, it will default to 20 returned results
  • The maximum is 200 hotels per request. This can be raised to 250 if required via API configuration.

If the total available results exceed the specified numberOfResults, the moreResultsAvailable flag will be returned as true. To request the next page of results, take the cacheKey and cacheLocation from the response and make another list request containing only these fields. No other elements are needed to page as the results are stored on the EAN API cache.

Effective Usage & Load

The EAN API is distributed among a large number of EAN Affiliates. Each request to the EAN API results in many subsequent upstream requests inside the Expedia inventory stack. Results must be gathered and sorted for every combination of factors such as hotel, rate, product, currency, promotion, point of sale, tax and promotion available.

Partners are advised to streamline their usage of the EAN API as much as possible to ensure that they have healthy ratios of List and Avail requests to Reservation request.


Careful consideration should also be given to the amount of load being exerted on the EAN API for List and Avail requests. A search for an area with a large number of possible hotels (e.g. London) will consume a much larger amount of processing power than a more focused search for a smaller area (e.g. Oxford Street, London). If possible, exclude properties that you know will not be of interest to your customers.

Use of the maxRatePlanCount Element

It is possible to configure the number of rates to be returned per hotel in the List response. By default, List will respond with one rate (the cheapest) per hotel. Research has found that this is the best-converting approach.

  • Each increment of this value will result in more work for the EAN API.
  • For example, if you set maxRatePlanCount=5 and the hotel has 5 or more available rooms the EAN API will return 5 hotel rooms and their prices. As such 5 times the load and slower response times.
  • We suggest that the Availability Summary request is used to retrieve all available rates and room types at the property when your user selects it from the List result.
  • If your site must offer multiple rates per property, we suggest a limit of 4 rates, as this is will give a good number of options for a customer to choose from.


Speed Basics

A speedy site or app is important for any online travel business. To ensure your customers can search and book as quickly as possible, your site should be using EAN’s API as efficiently as possible.

Ensure your site is accepting compressed API responses. Data transfer times from EAN will be significantly reduced, as will bandwidth consumption.

Use slim response options to return smaller, tailored list and room responses. When used in conjunction with local copies of our static database files, you can rely on your own servers for static data rather than waiting to extract the data from our API responses. The biggest speed benefits by using this combination will be found in the Hotel List request.

Set the request’s options parameter to ROOM_RATE_DETAILS. The hotel list response will return only dynamic rate information and a minimum of static information using this option. If you use the list request for simple availability checks or other situations where even dynamic rate data isn’t necessary, you can send HOTEL_SUMMARY for the slimmest and fastest possible response.

The Availability request features an options parameter as well. You can choose to return only room types, amenities, images, etc. and supplement the rest with your own static databases.
For any instance where you use static database files, remember to keep your static databases up to date.

Hotel Availability

Availability Request (Summary)

The availability request will return all rooms in a specific property for the occupancy and dates specified. Use this request to get all rooms and rates, the hotel information, fees, policies, images etc. By using the data in the availability response, you can create a complete Hotel Detail page that can provide all the necessary information for a successful booking. Please send includeDetails=false for quick responses and less API impact.

Availability Details Request
This is a specific version of the availability request to confirm pricing and availability of the selected rate prior to making your reservation.
Use the same method as in the availability request above, but add to the request:

  • RoomType
  • RateCode
  • rateKey
  • includeDetails set to TRUE

This request should be made on the checkout page, prior to a booking, to present possible availability and price changes. Ideally, the Availability to Reservation ratio should be almost 1:1.

Availability Usage

The Availability request is a very detailed, property-specific function. We recommend that this function is used to populate Hotel Details pages as a second step in the shopping path where a customer has selected a hotel from a preceding List result. The user will see the rate that interested them initially, together with all other available options and rates.
This request should not be automated or used excessively, as it is very costly to the EAN API’s inventory systems.


Static Content Files

You can complement your API calls by using our static EAN database files to have control on content and save time in transport/speed.

Speed up pages by storing all data on a local server rather than pulling everything from the API.
By optimizing processes to utilize the reduced content result options in the API and extracting static content from a local database, you can speed up pages for better user experiences. Review the static content available in the database files and how you can reduce result size with content options in the API. Consider caching static pages, such as hotel information, that are not combined with any dynamic availability.

  • Utilize static content in local database systems where possible. When using content locally, insure a process of updating the material frequently is in place. Visit the Database Catalogs pages to review all static content that can be downloaded and used locally.
  • Control the size of the data transfer in a hotel list response by specifying the data response option desired. When using static content from local resources, opt to receive only the dynamic content in the hotel list result, such as the Room Rate Details, rather than all default response content. In this way, all important content can still be displayed to the user, but minimal data is actually from the API, which optimizes the speed of the page.

Regardless of which of our database files you use or how you use them, you should refresh at least once per week to avoid errors and conflicting information.


Consuming Taxes & Fees

This is how surchargeTotal is derived and how each possible value of the Surcharges array adds up into the total value (paid at time of booking). Please see below a graphic that better explains this breakdown followed by the text extract:

Possible values of the surcharge array:

  • TaxAndServiceFee
  • ExtraPersonFee
  • Tax
  • ServiceFee
  • SalesTax
  • HotelOccupancyTax

Only TaxAndServiceFee and ExtraPersonFee contribute toward surchargeTotal. All other values are individual components of the TaxAndServiceFee value.
Here is an example XML response with real values overlaid on top of the above image:

Tax + ServiceFee + SalesTax(1)[$222.50] + HotelOccupancyTax <= TaxAndServiceFee(2)[$233.50]

TaxAndServiceFee(2)[$233.50] + ExtraPersonFee(3)[$160] = surchargeTotal(4)[$393.50]

surchargeTotal(4)[$393.50] + nightlyRateTotal(5)[$1348.40] = total(6)[$1741.90]

Taxes & Fees Not Included in Price

<ChargeableRateInfo averageBaseRate="24.22" averageRate="24.22" commissionableUsdTotal="48.44" currencyCode="USD" maxNightlyRate="24.22" nightlyRateTotal="48.44" surchargeTotal="7.32" total="55.76">
<NightlyRatesPerRoom size="2">
<NightlyRate baseRate="24.22" rate="24.22" promo="false"/>
<NightlyRate baseRate="24.22" rate="24.22" promo="false"/>
<Surcharges size="1">
<Surcharge type="TaxAndServiceFee" amount="7.32"/>
<HotelFees size="1">
<HotelFee description="ResortFee" amount="10.00"/>

Highlighted in red above is the hotelFees array. This is provided outside of ChargeableRateInfo and is not part of the total. The currency applicable to the hotelFee array is the currencyCode attribute taken from within ChargeableRateInfo. Possible values of this array are:

  • MandatoryFee
  • MandatoryTax
  • ResortFee
These amounts are payable by the customer at the property and are not part of the total price returned in ChargeableRateInfo.

Value Adds

Increase sales conversions by including Value Add information with room types.
Value adds are special values or services offered by the property included in the price of the room. Display them alongside room types on your hotel list and room availability pages to increase conversion.

The way in which you can use this is by mapping / converting the value adds to internal or appropriate extras

A list of known value adds can be found on the following page;

Converted Rates vs Chargeable Rates

When you call the EAN API you are able to request hotel prices in a selected currency.

  • Chargeable rates are the chargeable values to be used at booking time, regardless of the currency requested in the shopping path. Use the values contained within this element to avoid possible Price Mismatch or Sold Out errors.
  • Converted rates or display rates are converted rates only if the currency requested is not the hotel's native currency(Hotel Collect), or is not supported as an Expedia Collect payment option.

In this example the currencyCode was passed as ZAR. The API returned ConvertedRateInfo which could be used to display ZAR values to the users. However, the USD currency and values contained in ChargeableRateInfo must be used to make the reservation.

For a list of available currencies and there available reservation currency click here

EAN Images, Size & Coverage

Hotel images are often considered the main drivers of conversion. Images can be retrieved from the API and our static content files. When building pages, you want to be able to display the images as quickly as possible and using the static files is often considered the best way of doing so.

In the API, we typically expose three image sizes. Here are examples taken from our HotelInfo API response:
These three image URLs are exactly the same other than the last part of the file name:
1. The thumbnail ends with _t.jpg
2. The big size image ends with _b.jpg
3. The high resolution size image ends with _z.jpg - Please note that not all properties will return this image option.

It is possible to get other images sizes(where available) by altering the image links.








Still Image







Still Image







Still Image







Still Image







Still Image







Still Image







Still Image







Still Image







Still Image







Full coverage of each image size above is not guaranteed. In the example below, the image that ends in _z is not available. In these cases, make sure that your script can reselect an alternative image from the list.

For more resources for image information go to:
Hotel Image Categorization Image Data


Hotel Collect Rates

For Hotel Collect (HC) rates, payment is collected directly by the hotel. Funds are typically captured in the hotels local currency.

Local Currency Change

  • For Hotel Collect rates, the hotel will most likely charge in their local currency. This will be the currency returned in the chargeableRateInfo node. If shopping requests are made in a currency different to that of the property, a ConvertedRateInfo node will also be returned in order to display rates in that currency without having to make conversions within your integration.
  • Send an API payment types request with the hotelId and ratetype=DirectAgency to obtain a list of accepted credit cards accepted at checkout by the property.

Rate InfoObject
When dealing with Pre- and Post-Pay results, the rateInfos object returned in a rate may contain two rateInfo items (1 for the Pre-Pay rate & 1 for Post-Pay rate). Your integration should read and display both of these rates for the user to select and Book accordingly.

Static Content Database for Hotel Collect

  • An extended content database file is available which includes extract properties that offer Pre, Post, and combined Pre+Post-pay rates. It is recommended to download these files locally in order to speed up in results / rendering.
  • Please request access to this database and documentation via your Account Manager or Integration Consultant.


Making Successful Reservations

Booking Request

The reservation request is used to create the booking. The response will present the user with an EAN itinerary number and the hotel confirmation ID(s). Please make sure to store and present both IDs.

  • If EAN is the merchant of record (EAN takes payment from your customer’s card) make sure to check the available payment types.
  • URL encode your request
  • Use as your endpoint


Test Booking/Live Test Booking/EAC

Test Bookings

In order to ensure you are successfully able to make a booking, it is part of our launch requirements to create test bookings. Please pay special attention to the following items:

  • Static contact and credit card details found on the EAN developer site.
  • Use ‘travelnow’ as the text for addressLine1. This will prevent the creation of an actual live booking by mistake.
  • Always attempt to book a room at least 3 months in advance.
  • Ensure the room rate is fully refundable (even if it is a test booking).
  • The confirmationNumber in the reservation response will always return as ‘1234’ to indicate test booking

Live Test Bookings

Live test bookings may be required if your integration uses EAC as a payment method. In addition to the above guidelines, please also follow these points:

  • Do not use travelnow in address line 1, as this will not create a live booking.
  • Please make sure to use a hotel with a fully refundable rate, booked well in advance in the future, so you can cancel the reservation IMMEDIATELY after making the booking.
  • EAN will not be liable for non-refundable hotels that can not be cancelled.

Error Handling

Error handling forms a big part of successful partner integrations. It is always best practice to embed error handling into any process and effectively manage any problems that may occur.
The EAN API has implemented extensive error handling structure to best inform partners of problems that may occur as a response to a request.

Resending a Reservation

Include the itineraryId returned in the error response if this is a second booking attempt.
When recovering from an error message, provide the previous itineraryId to avoid duplicate bookings and reporting.

After an availability response is returned, you will note ChargebleRateInfo is returned – this is the currency that will be used to pay for the reservation. For example, if you request EUR and the hotel it is available to be reserved in EUR, then it will be returned in the ChargebleRateInfo object. Otherwise, it will default to USD.


The error can be handled depending on the handling type and the category, in most cases you can resubmit the request to process and it should respond appropriately if it has been rectified.
Special attention should be given to the following elements:
<handling>RECOVERABLE</handling> Determines if the error can be handled in order to reach a successful result.
<category>AUTHENTICATION</category> indicates the type of failure.

Preventing Duplicate Bookings

The affiliateConfirmationId value is designed for tracking bookings for reconciliation and to help prevent duplicate bookings. Our systems detect if the value sent has already been used for an existing booking, preventing from proceeding through our downstream reservation systems creating duplicates.

This field can also be used to send partner-specific values through the API which can later be retrieved from EAN statements to assist with reconciliation. See our tracking bookings page for more information on this usage. In the event of an error, the affiliateConfirmationId used in the retry should be different than the original request to avoid the original error response being returned.

Add this parameter to your request elements. For XML, this must be outside the XML body.

Pending Process

The vast majority of reservations respond within a few seconds. However, for various technical and operational reasons, the odd reservation may respond with a pending state, or may take several minutes to respond. It's important to note that pending status' do not guarantee confirmed bookings so you should be providing the customer with a final status update on whether the reservation was successful or not prior to arrival at the property.It is the partner’s responsibility to keep track of the reservation until a response is received.

Hence you need a strategy for dealing with pending or delayed responses.

Some EAN Partners choose to present a reservation error to the end customer and offer them alternative rates if the original attempt was fully refundable. The Partner will monitor the status of the Pending booking until it confirms or is cancelled. In the case that it confirms they will automatically cancel the booking.

There are various strategies for non-refundable bookings that can be adopted at the cut-off time you deem appropriate, for example:

  • Advise the customer that the booking is pending and will be confirmed later by email (our recommendation)
  • Allow the customer to book an alternate reservation and then ask the EAN call-centre to try to obtain a refund if the original booking subsequently confirms (risky because the refund is not guaranteed).
  • Tell the customer the booking is confirmed and then manually reallocate the customer to another booking if the confirmation subsequently fails.

In the case of the first point above, we recommend that after waiting 2 hours you contact the EAN call-centre and ask for assistance to resolve the issue.

In terms of testing, you can force a ‘pending’ reservation status by adding the value ‘travelnowpending’ to your address1 element in the reservation request.

For more information on simulating errors for testing, see our Force Errors page.

Price Change Errors

Due to the dynamic nature of EAN rates and availability, prices may change between shop and book steps. This can cause a recoverable reservation error which can be recovered by making the request again with the updated price (returned in the error message).

The best way to avoid this error is to perform an Avail Detail call prior to booking. Any change in local, customerIpAddress or currencyCode between List, Avail and Book can also cause a price or availability to change and these three elements should remain the same throughout the shopping path.

For a detail list of how to handle price changes go to:


Email / Voucher: What to Give a Customer

Pre-Pay / Post-Pay
You have the option of using EAN's email voucher service to send out confirmation, pending, cancellation emails once a booking has been made, or you can choose to use your own service to send emails to customers.

Due to the opaque nature of providing Packaged Hotel and Travel offerings, partners are required to generate their own email voucher with the combined total cost of the hotel with the transportation component.


When sending your own confirmation emails, it’s very important that sufficient information is proved to the end customer for them to be able to manage their booking easily and check into the property without issues. In the case of the partner cancelling the booking via your integration and or directly via the manage my booking link on the EAN confirmation email it’s very important that these changes are picked up and reconciled within your systems.

Itinerary Request

Using the itinerary request will retrieve a booking and its booking status. While not necessary for a strict booking flow, this call is essential for advanced exception handling and can also be used to present bookings at a later point to the customer, building the basics of a customer service portal.
Itinerary request has a number of functions:

Checking status of a Pending Status booking
As covered in error handling for pending status process fail cases. This occurs when you do not immediately get a confirmed booking.

Pending Status
Itinerary ID - For this you need the itineraryId from the booking response.

Timeouts / Prevent Duplicates
Include the following parameter from the Booking request to pull back the status of a suspected time out booking
AffiliateConfirmationId – Designed to check if any subsequent requests have been sent and flag them up as a duplicate. Always send the same AffiliateConfirmationId as you did in a res call when you get a timeout to check if the booking has now resolved in a CF or CX status.

Reconciling Bookings

  • Use the itinerary request to reconcile bookings made over the last 24 hours or by creation date.
  • Ensure all bookings made were successful and to cross check any booking against your own list of bookings.
  • This is especially important if you are using EAC finance to stay on top of any bookings which were successful which you thought had errored out and cancelled.
  • In the event that you find a successful booking which was by mistake please contact our GCO team ASAP for assistance.

Note: Since this response returns customer information, deliver any user-facing data via HTTPS.

Cancellation Request

The cancellation request in the API allows cancellation of a confirmed booking. A confirmed booking will have an itineraryId, a hotel confirmation ID and the booking status CF.

While a cancelled booking is not desirable, it is better for a customer to cancel via the API than a customer service agent, reducing the workload for your customer service team.

  • Allow customers to cancel an existing booking through your site via a self-service portal or have them call your agent who has the ability to cancel a booking for them
  • It is important to make the cancellation policy clear to the customer: whether it is free cancellation to a certain date or time, or non-refundable from time of booking. This should be made clear along with any charges the customer will incur.
  • Ensure you use the cancelPolicyList array returned to determine the charges the customer will be liable for, so they or the agent is aware when confirming the cancellation.
  • When testing the Cancellation API call, it is normal behaviour for the API to return an error when cancelling a test booking.

Protecting User Privacy

Send all pages with sensitive information via HTTPS.
All affiliate websites must protect user's privacy regarding ALL sensitive, personal, and financial data. (Reservation, Itinerary, Cancellation Requests)

Secure the user's transmission of payment and personally identifiable data by using a secure certificate with any forms servicing email addresses, names, payment information, physical addresses, phone numbers, etc.
• All booking forms, confirmation, itinerary, and cancellation pages MUST be secured with a trusted certificate.
• NO bank card numbers are to be re-displayed on any of these pages once the user has entered the information.
• NO bank card numbers should be stored in any affiliate applications as this is a violation of PCI policies.
• Because EAN is the host of the transmission of data from your server to our servers, EAN are responsible for providing the certificate. Your certificate will not be used in this transmission.
• Failure to send your reservation request to us with the HTTPS protocol will result in an exception message.