Requests a reservation for the specified room(s). This request must be sent with the POST method via HTTPS to protect the customer's payment information. The information submitted in this request is subject to EAN's proprietary fraud and security validation methods.

The credit card information provided in the request will be used for a direct prepayment of the reservation. The customer's reservation is paid in full (save any extras like room service) as soon as a successful response is received, even if booking months in advance.

Be certain to use the correct cid/apiKey pair for live bookings. This is critical both to placing successful bookings and ensuring any commissions earned are paid out to the correct account.

If you are experiencing input validation errors for city, address, or firstName and lastName values, please note that the API currently only supports the UTF-8 Basic Latin and Latin-1 Supplement character sets. Languages that use characters unsupported by these charsets, such as ő or ű, must be filtered or converted to avoid input errors.


Request Formats
XML/REST URL: POST https://book.api.ean.com/ean-services/rs/hotel/v3/res
XML Parent Element: <HotelRoomReservationRequest>

To avoid URL length limit issues, send your booking request parameters within the POST body as application/x-www-form-urlencoded data.
All common elements must be sent in the same format used for GET requests - do not attempt to format these values as elements within the POST body.



Request Parameters

Service-Specific URL Parameters
Name Value Required Description
currencyCode string yes Always use the attribute value returned in the previous response's ChargeableRateInfo node when populating this parameter for a booking request.
Using other sources for this value may cause mismatch errors.
additionalData container for MapEntry no

Use this booking-only parameter to help track bookings in the EAN Affiliate Center. See our track bookings page for full documentation.



Base Parameters
Name Type Required Description
apiExperience string yes

Use this attribute to identify the origin of your request. Choose an applicable value from the set provided below for each request you send.

Values:
PARTNER_CALL_CENTER - request from an agent in your call center
PARTNER_WEBSITE - request from a customer-facing website
PARTNER_MOBILE_WEB - request from a mobile-formatted website
PARTNER_MOBILE_APP - request from a mobile app
PARTNER_BOT_CACHE - request from a cache bot
PARTNER_BOT_REPORTING - request from a reporting bot
PARTNER_AFFILIATE - request from an API/platform that serves your own affiliate base

hotelId long yes ID of the property for the reservation to be requested
arrivalDate string yes

Check-in date, in MM/DD/YYYY format. Carry over value from the room response.

Bookings may be made up to 11:59PM local hotel time (9:59PM for PST and Pacific islands).

departureDate string yes Check-out date, in MM/DD/YYYY format. Carry over value from the room response.
supplierType string yes Defines the suppier to be used to carry out the booking. Carry over value from the room response.

Values:
E: Expedia Collect
rateKey string yes Validates the parameters stated in the booking request. Carry over value from the room response. Use the rateKey returned within the first Room object in the room response for the best performance.

If any value other than the one provided in previous room response is used, the booking will fail.

If you choose to allow customers to modify any parameters at the booking stage, resend those parameters in a new room request to obtain a new valid value for this parameter.

Errors referring to "Invalid QueryId" or rate cache errors suggest the key has expired or invalid. Resend the previous room request to obtain a new value, even if no parameters have changed.
roomTypeCode string yes Code designating the specific room requested. Always obtain dynamically from the previous room response.

Send together with rateCode
rateCode string yes Code designating the rate paired against the specific room requested. Always obtain dynamically from the previous room response.

Send together with roomTypeCode
RoomGroup object yes Container for the Room arrays that define guest and room count. Use the same values for adults, children, and child ages as defined in the previous room request.

Additional parameters for this object are required specifically for reservations - see below.
RoomGroup.Room array yes The number of Room nodes defines the number of rooms requested. Include the same number of nodes and the same guest count/age parameters as defined in the previous room request.
Room.numberOfAdults int yes Adult guest count for the room. Use the same value as defined in the previous room request.
Room.numberOfChildren int yes if > 0 Child guest count for the room. Use the same value as defined in the previous room request.
Room.childAges comma-separated
list of int
yes if child count > 0 Ages of child guests, if any. Use the same value as defined in the previous room request. EAN considers individuals between the age of 0-17 to be children.
Room.firstName string yes Full first name of the guest checking in for the reservation. Name must match guest's photo ID when checking in at the property.

25 char max - no salutations or company names. Guest names do not need to be unique to each room.
Room.lastName string yes Full last name of the guest checking in for the reservation. Name must match guest's photo ID when checking in at the property.

40 char max - no salutations or company names. Guest names do not need to be unique to each room.
Room.bedTypeId string yes Code for the bed customer's bed choice (or single value if no choice was offered).

Carry over the matching value from the BedType ID attribute from the customer's selected room in the room response.

Choices between multiple bed types for the same room are requests only and may not be honored at the hotel if availability does not permit.
Room.numberOfBeds int no Value of 1 or 2. Request only - offer only if sensible based off of BedType options returned in the room response.
Room.smokingPreference string yes if used Requested smoking preference. Omit this element entirely from your request if not needed for a given booking.

Possible values:
NS: non-smoking
S: smoking
E: either

Only offer values that were returned in the room response - do not use the above values as hard-coded choices. Including a value not provided in the response will cause a booking failure. Do not send multiple values.
affiliateConfirmationId string yes Value designed for tracking bookings and to help prevent duplicate bookings.

Generate a unique value such as a GUID ID (36 char. max) prior to submitting the booking. If the API detects the value paired with an existing booking, it will prevent all subsequent bookings as duplicates.

To prevent valid booking retries from being rejected, always create a new value if re-attempting a booking that failed due to an error other than a timeout.
affiliateCustomerId string no Additional optional customer ID for use with partner-side tracking. Only use this ID internally, as accidental exposure can allow retrieval of itineraries not belonging to the customer.
itineraryId long no

If an initial reservation request returns with a credit card error, extract this value from the response and include it in any subsequent booking attempt.

When passed again, this value is paired against the existing itinerary record that was generated by your first request. Any repeated credit card declinations or errors will be confined to a single record to avoid the appearance of multiple cancellations in any statistics.

Only expose this value to customers if you are using EAN support (you do not have your own support agents).

Do not resend this value if it returns as -1. This indicates an itinerary was not created. Begin again with a new request after messaging the error and allowing the customer to correct if needed.

chargeableRate string yes The total amount to be charged for the reservation.

Carry over the value of total from the ChargeableRateInfo object returned in the room response.

Upon submission of the request, this rate is validated against the latest known rate for the provided room and rate codes. If the latest rate is higher, an error is returned containing the new higher rate and its matching rateKey value. If it is lower, the request passes with the new lower rate.
specialInformation string no

Allows the customer to add extra information or requests to pass along to the property.

Any info within is a request only and not guaranteed – do not use this field to communicate B2B customer service requests or pass any sensitive personal/financial information.

256 char max with no line breaks or carriage returns. Any line breaks or carriage returns not stripped from this parameter will cause an unrecoverable error.

sendReservationEmail boolean no

Send as false if you send your own confirmation emails; omit otherwise.

Only use this parameter if you have already consulted your account manager or support about your own confirmation email system.

Payment Information Parameters
These parameters define the information used to validate and charge the customer's credit card for payment.

Information for payment is provided via the ReservationInfo object and the AddressInfo object. Applicable values within both objects are validated against the issuing bank's information for the cardholder.

Some systems used for payment validation and processing cannot parse non-Latin characters - ensure that only Latin character values are allowed for all paramters to avoid data validation errors.

See our best practices for requesting and processing card information in the validation section of our credit card types page.

Name Value Required Description
ReservationInfo object yes Contains the customer's contact and credit card information.
ReservationInfo.email string yes Customer's email address. EAN (travelnow.com) confirmation email is automatically sent to this address. Must be a valid email address, even if your integration treats this field as internal-only..
50 char max for the entire address, including @ and .
ReservationInfo.firstName string yes Full first name of the credit card holder.
25 char max - no salutations or company names.
ReservationInfo.lastName string yes Full last name of the credit card holder.
40 char max - no salutations or company names.
ReservationInfo.homePhone string yes

Customer's home phone number. Used by a customer service agent if the customer needs to be contacted to resolve a problem with their reservation.

Numbers must be at least 5 digits long. Restrict characters to 0-9, +, -, and ( ).

ReservationInfo.workPhone string no The customer's work phone number. Numbers must be at least 5 digits long. Restrict characters to 0-9, +, -, and ( ).
ReservationInfo.extension string no The customer's work phone number extension, if needed. 5 char max.
ReservationInfo.faxPhone string no The customer's fax number. Numbers must be at least 5 digits long. Restrict characters to 0-9, +, -, and ( ).
ReservationInfo.companyName string no Company name, if needed for employee travel receipts or tax purposes
ReservationInfo.creditCardType string yes The type of credit card being used. Review this page for specific values for credit card types and details on validation.
ReservationInfo.creditCardNumber string yes Customer credit card number.
ReservationInfo.creditCardIdentifier string yes Credit card identification number or the card security value (CSV or CVV) that is found on the back of the card. Never store this value after the customer's initial entry and booking attempt.
ReservationInfo.creditCardExpirationMonth string yes Credit card expiration month, in MM format.
ReservationInfo.creditCardExpirationYear string yes Credit card expiration year, in YYYY format.
Address Information
Cardholder address information is sent in an object separate from payment card details in ReservationInfo. Special values may be used in this object during development to perform static test bookings.
Name Value Required Description
AddressInfo object yes Contains the cardholder address information. This information must match the credit card provider's records for payment to be processed successfully.
AddressInfo.address1 string yes The customer's street address, 28 char max. Ensure special characters are properly encoded.
AddressInfo.address2 string no Optional second line for street address, 28 char max.
AddressInfo.address3 string no Optional third line for street address, 28 char max.
city string yes Customer's city.
stateProvinceCode string yes for US,
CA, AU
Two character code for the state/province containing the specified city. For Australia, you must use the special codes provided below.

References:
US State Codes
Canadian Province/Territory Codes
Australian Province/Territory Codes
  • Australian Capital - AC
  • New South Wales - NW
  • Northern Territory - NO
  • Queensland - QL
  • South Australia - SA
  • Tasmania - TS
  • Victoria - VC
  • Western Australia - WT
countryCode string yes Two character ISO-3166 code for the country containing the specified city. Use only country codes designated as "officially assigned" in the ISO-3166 decoding table.
postalCode string yes Customer's billing postal code. Maximum of 10 characters. US bookings must use 5 digit postal codes only.
This value must match the credit card provider's records or the booking will not be valid.
Label this field as "Billing Postal Code" or "Billing ZIP Code" to reduce failures. Valid characters are alphanumerics, spaces, underscores ( _ ), and hyphens ( - )


Reservation Response
Confirms the successful booking of the requested rooms, or provides information about the status of the reservation if it was not confirmed as successful.

The response for a successful booking also contains the customer's itinerary number, their confirmation number, and a confirmation of their room selection and the price they paid.

Since this response contains customer data, return the data to users securely via HTTPS.

Response Content
Parent Element: HotelRoomReservationResponse


Name Value Description
itineraryId long

EAN's unique ID for the reservation.

Used along with the booking confirmation number for any communication that EAN or your own customer service department makes with the customer. Ensure both values are clearly provided to the customer.

Note: For hotels that use Expedia Partner Central, itineraries cannot be located using this value . Use the EXPEDIA_BOOKING_ITEM_ID confirmationExtras value in a follow-up itinerary request to return a value compatible with EPC.

confirmationNumbers array

Confirmation number(s) for the booking, one per room booked. Generated by EAN's reservation database.

This value is used along with the itinerary ID for any communication that EAN makes with the customer. If you send your own emails and you rely on EAN support (you do not have your own agents), ensure both values are clearly provided to the customer. If you use agent-to-agent support, do not provide this value to customers.

Multi-room bookings will return a standard confirmation number for the first room. The remaining rooms will have the same confirmation number appended with a hyphen and a number, starting with 1, e.g. 120467481181, 120467481181-1, 120467481181-2

processedWithConfirmation boolean Indicates if the hotel itself confirmed the reservation as it was processed.

When returned as false, indicates the property has not yet returned a confirmation number for the reservation. The reservation will likely return with a PS status.

In these cases, an EAN agent will monitor the booking until it is fully confirmed. The confirmation email will advise the customer that a confirmation number will be forwarded by an agent as soon as it is provided.
errorText string Any error text that may have been generated during the booking process in addition to the contents of the EanWSError common element.
hotelReplyText string Any information received from the hotel at the time of booking
supplierType string Confirms the supplier system used to process the booking.
reservationStatusCode string Indicates the status of the reservation in the supplier system at the time of booking. Anticipate appropriate customer messaging for all non-confirmed values.

Values:
CF Confirmed
CX Cancelled
UC Unconfirmed. Treat this status the same as DT. The API will never assign this status to live bookings.
PS Pending Supplier. See our pending process guide.
ER Error. May occur when booking needs agent attention, or for a declined credit card. If a credit card error returns, alert the customer appropriately. If they try to book again, resend the itineraryId returned in the failed booking response.
DT Deleted Itinerary (Usually a test or failed booking)
existingItinerary boolean Indicator for a prevented duplicate booking, used in conjunction with the affiliateConfirmationId request parameter. Returns as true along with the existing successful itinereary if the same confirmation value is sent more than once.
numberOfRoomsBooked int Confirms the number of rooms booked. Will match the number of confirmation numbers returned.
drivingDirections string Typically empty, not recommended for display.
checkInInstructions string Check-in instructions for the hotel.
specialCheckInInstructions string Contains information critical for check-in, such as a requirement to notify the property of an expected arrival time. Display this information in the same area as the primary check-in instructions.
arrivalDate string Confirmation of check-in date
departureDate string Confirmation of check-out date
hotelName string Name of the hotel booked
hotelAddress string Hotel street address
hotelCity string Hotel city
hotelStateProvinceCode string Two character code for the state/province containing the specified city. Returns only for US, CA, and AU country codes.

References:
US State Codes
Canadian Province/Territory Codes
Australian Province/Territory Codes
hotelCountryCode string Two character ISO-3166 code for the country the hotel is located in.
hotelPostalCode string Hotel postal code
roomDescription string Short description of the room booked
rateOccupancyPerRoom int Confirms how many guests are guaranteed for the room booked.
RateInfos container for RateInfo Contains an array of RateInfo elements that provide detailed rate information for individual rooms.

If you are using an older integration running on minorRev=6 or earlier, RateInfo will return without the RateInfos container.
RateInfos.RateInfo object Contains all rate information for a single room within several different objects and individual values.

Attributes:
priceBreakdownboolean Indicates if a full price breakdown including taxes and total price to be charged is included.
promo boolean Indicates if the rate returned is a promotional rate.
rateChange boolean Indicates if the rate is different for at least one of the nights during the stay.
RateInfo.cancellationPolicy string Cancellation policy for the property. Display required.
RateInfo.CancelPolicyInfoList array Details specifics of the cancellation policy, typically the times determining the penalty period and the penalties incurred for cancellation.
Review details for the CancelPolicyInfo array
RateInfo.nonRefundable boolean Confirms value returned in the room response. If returned in a successful booking response as true, the amount charged is final. For Expedia Collect only.
RateInfo.ChargeableRateInfo object This object's attributes contain the absolute total to be charged for the reservation as well as rate averages and totals. Nodes within the object provide details on individual nightly rates and surcharges.

Attributes:
total string The total of all nightly rates, taxes, and surcharges to be charged for the reservation. This is the total value that must be displayed to the customer and included in the booking request.
surchargeTotal string Total of TaxAndServiceFee and ExtraPersonFee from the Surcharges array. These fees are collected by Expedia upon booking.
nightlyRateTotal string Total of all values in the nightlyRatesPerRoom array contained within this object.
maxNightlyRate string Highest nightly rate of all rates returned
currencyCode string Currency code for the rates returned
commissionableUsdTotal string Do not use this attribute. This value is no longer maintained.
averageRate string Average of all nightly rates with any promo values applied, without surcharges.
averageBaseRate string Average of all nightly rates without any promo values applied, without surcharges.Will return the same as previous value if no promos present.
ChargeableRateInfo.nightlyRatesPerRoom array Container for NightlyRate array. Has size attribute to indicate number of nodes in the array, which will correspond to the number of nights in the request. Rates return in sequential order across the duration of the stay.
nightlyRatesPerRoom.NightlyRate n/a Details the rate for a single night within the span of the requested stay. Indicates the presence of a promo rate, the base rate, and the rate after the promo is applied (if applicable). Contains attributes only.

Attributes:
promo boolean Indicates if a promo rate is applied for this night's rate.
rate string The nightly rate after the promo, if any, is applied.
baseRate string The nightly rate before the promo, if any, is applied.
RateInfo.promoType string Indicates whether any promos returned are mobile-specific or standard promotions. Returns Mobile for mobile promotions and Standard for all others.
In order to return mobile promotions, you must identify your mobile site or app via the proper customerUserAgent string.
RateInfo.depositRequired boolean Indicates if a deposit is required at the time of booking to secure the reservation.
RateInfo.rateType string Indicates if the rate returned is prepaid via EAN or post-paid at the hotel. Either returns with a value of MerchantStandard for prepaid availability, or does not return at all for post-paid.
ChargeableRateInfo.Surcharges array

Container for Surcharge array. Details the individual charges that contribute to TaxAndServiceFee and surchargeTotal.

All taxes and fees contained with in this array are charged and collected by Expedia upon booking.

Contains size attribute to indicate number of nodes in the array.

Surcharges.Surcharge n/a

Details a single surcharge's amount and type. Contains attributes only.

TaxAndServiceFee and ExtraPersonFee contribute toward the surchargeTotal. All other values are individual components of the TaxAndServiceFee value:

Attributes:

amount float Amount of the specific surcharge
type string

Name of the surcharge.
Possible values:

Components of surchargeTotal:

  • TaxAndServiceFee
  • ExtraPersonFee

Components of TaxAndServiceFee:

  • Tax
  • ServiceFee
  • SalesTax
  • HotelOccupancyTax
  • PropertyFee

Important Display Rules:

•  The SalesTax and HotelOccupancyTax surcharge types must be displayed by state law in New York. Ensure you expect and capture these values to display as "Hotel Occupancy and Sales Tax" in the final price breakdown.

• The PropertyFee surcharge type must be displayed as "Property Fee" in the final price breakdown for the following Points of Sale:

  • US
  • Canada
  • Brazil
  • LATAM
RateInfo.HotelFees array

Any taxes or fees detailed within this array are charged and collected by the hotel upon check-in or check-out.

These fees are not charged or collected by Expedia – they are completely separate from those detailed in the Surcharges array.

When populated, use this element to meet the rate/tax/fee display format required by major search engines and aggregators.

Contains size attribute to indicate the number of charges contained.

HotelFees.HotelFee none

Contains attributes for the description, amount, and currency of a single fee.

Details the total of any VAT, state/city tax, resort fees, or any other fees collected that cannot be reasonably avoided.

Example: A $10 per-night charge for a 4-night stay will be represented by a value of 40.00

Charges return in the bookable currency indicated by the currencyCode attribute of ChargeableRateInfo.

Attributes:

description string The type of charge, e.g. VAT or resort fee
amount string Total value for the charge


RateInfo.RoomGroup object Container for the Room arrays that define guest and room count. Confirms the guest and bed details for each room booked.
RoomGroup.Room array Number of nodes will match the value of numberOfRoomsBooked.
Room.numberOfAdults int Adult guest count for the room.
Room.numberOfChildren int Child guest count for the room.
Room.childAges comma-separated
list of int
Ages of child guests, if any.
Room.firstName string Full first name of the guest checking in for the reservation.
Room.lastName string Full last name of the guest checking in for the reservation.
Room.bedTypeId string Code for the bed customer's bed choice (or single value if no choice was offered).
Room.bedTypeDescription string Description confirming the bed type choice.
Room.numberOfBeds int Value of 1 or 2.
Room.smokingPreference string Confirms requested smoking preference.
Room.ChargeableNightlyRates array Container for NightlyRate array for the room. Rates returned are specific to the individual room and return in sequential order across the duration of the stay.

For an average per-night cost across multiple rooms, use the values provided by nightlyRatesPerRoom.

Returns for minorRev=29 and higher.
ChargeableNightlyRates.NightlyRate object

Provides the rate for a single night within the span of the requested stay.

Indicates the presence of a promo rate, the base rate, and the rate after the promo is applied (if applicable). Contains attributes only.

For multi-room requests, this value is the average of the per-night cost across all rooms. EAN recommends using the new per-room ChargeableNightlyRates array for multi-room price display.

For multi-room requests under minorRev=28 and below, this element provides rates for the first room only, instead of an average rate.

Attributes:

promo boolean Indicates if a promo rate is applied for this night's rate.
rate string The nightly rate after the promo, if any, is applied.
baseRate string The nightly rate before the promo, if any, is applied.
ChargeableNightlyRates.
ConvertedNightlyRates
object Rate information converted to the customer's requested currency. Returned only if the requested currency is non-billable by the hotel or within the customer's market region. Contains the same attributes as ChargeableNightyRates. Returns for minorRev=29 and higher.
ValueAdds container for ValueAdd Contains all value adds included with the reservation. Has a size attribute to indicate the number of individual value adds.

Available with minorRev=28 or higher.
ValueAdds.ValueAdd array

Contains a description element describing an individual free service offered with the provided room and rate, such as free breakfast or wireless internet.

Available with minorRev=28 or higher.

ConvertedRateInfo object Rate information converted to the customer's requested currency. Returned only if the chargeable and converted currencies are different, i.e. if the hotel cannot accept the customer's requested currency. Contains the same attributes as ChargeableRateInfo.
Values returned within this object are not bookable. Attempting to book with a converted value will result in an error.