Deprecated API

The Legacy Pull Buyers API, our initial Buyers API launched in 2012, is now deprecated and should not be further developed. Instead, we introduced the Hotel-X Buyers API in 2017, which serves as the sole API for new Buyers looking to integrate and participate in our Marketplace.

Valuation

Valuation operation evaluates the rate before reservation, providing the same information as the Avail response for a hotel rate, including up-to-date pricing. Additionally, it offers further details such as rate breakdown and cancellation policies. The returned fields include: Status, Price, CancelPenalities, Fees, PaymentOptions etc.

caution

The amount of information returned might vary between Sellers.

Valuation Request

Suppliers with block allotment

There are some suppliers who use block allotments, sometimes called pre-confirmation or quote. In that case, you will have 30 minutes to complete the booking, if not, you will have to re-launch Valuation 30 minutes after the last request, normally just before booking request.

<soapenv:Envelope xmlns:soapenv = "http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns = "http://schemas.xmltravelgate.com/hub/2012/06" xmlns:wsse = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <soapenv:Header>
      <wsse:Security>
         <wsse:UsernameToken>
            <wsse:Username>username</wsse:Username>
            <wsse:Password>password</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <ns:Valuation>
         <ns:valuationRQ>
            <ns:timeoutMilliseconds>20000</ns:timeoutMilliseconds>
            <ns:version>1</ns:version>
            <ns:providerRQ>
               <ns:code>suppliercode</ns:code>
               <ns:id>1</ns:id>
               <ns:rqXML>
                  <ValuationRQ>
                      <timeoutMilliseconds>19700</timeoutMilliseconds>
                     <source>
                        <languageCode>en</languageCode>
                     </source>
                     <filterAuditData>
                        <registerTransactions>true</registerTransactions>
                     </filterAuditData>
                     <Configuration>
                        <User>user</User>
                        <Password>password</Password>
                        <UrlAvail>www.supplier.com/avail</UrlAvail>
                        <UrlReservation>www.supplier.com/reservation</UrlReservation>
                        <UrlValuation>www.supplier.com/valuation</UrlValuation>
                        <UrlGeneric>www.supplier.com/generic</UrlGeneric>
                        <Parameters>
                           <Parameter key = "UrlListHotels" value = "http://www.supplier.com/ListHotels"></Parameter>
                           <Parameter key = "Access" value = "22334"></Parameter>
                        </Parameters>
                     </Configuration>
                     <StartDate>04/07/2016</StartDate>
                     <EndDate>11/07/2016</EndDate>
                     <MealPlanCode>15</MealPlanCode>
                     <HotelCode>6259</HotelCode>
                     <PaymentType>MerchantPay</PaymentType>
                     <OptionType>Hotel</OptionType>
                     <OnRequest>false</OnRequest>
                     <BlockOption>false</BlockOption>
                     <Nationality>ES</Nationality>
                     <Parameters>
                        <Parameter key = "ID1" value = "ID#1#VR"/>
                        <Parameter key = "ID2" value = "ID#2#FGR#45187#10-5"/>
                        <Parameter key = "PSR" value = "511.28"/>
                     </Parameters>
                     <Rooms>
                        <Room id = "ITD10" roomCandidateRefId = "1" code = "TW" description = "Twinn"/>
                        <Room id = "IOG22" roomCandidateRefId = "2" code = "IND" description = "Individual"/>
                     </Rooms>
                     <RoomCandidates>
                        <RoomCandidate id = "1">
                           <Paxes>
                              <Pax age = "30" id = "1"/>
                              <Pax age = "30" id = "2"/>
                           </Paxes>
                        </RoomCandidate>
                        <RoomCandidate id = "2">
                           <Paxes>
                              <Pax age = "30" id = "1"/>
                           </Paxes>
                        </RoomCandidate>
                     </RoomCandidates>
                  </ValuationRQ>
               </ns:rqXML>
            </ns:providerRQ>
         </ns:valuationRQ>
      </ns:Valuation>
   </soapenv:Body>
</soapenv:Envelope>

Request Data Breakdown

info

Check the values you need to add in the header and common elements.

Element

Rel

Type

Description

ValuationRQ

Root node.

ValuationRQ/StartDate

String

Start date of rate search.

ValuationRQ/EndDate

String

End date of rates search.

ValuationRQ/OnRequest

Boolean

Indicates if you want to receive the on request options in AvailRS, as long as the supplier returns it in this method (see MetaData).

ValuationRQ/BlockOption

Boolean

Indicates if you want to block the option selected in AvailRS, as long as the supplier allows it in this method (see MetaData).

ValuationRQ/MealPlanCode

String

MealPlan code.

ValuationRQ/HotelCode

String

Hotel code.

ValuationRQ/PaymentType

String

Payment Types

Code	Description
MerchantPay	The payment is managed by the supplier.
LaterPay	The payment is managed by the hotel. The customer will use a credit-card as a guarantee for the hotel and the payment will be completed at check in.
CardBookingPay	The payment is managed by the supplier. The payment is effectuated at the time of booking.
CardCheckInPay	The payment is managed by the supplier. The payment is effectuated at check in in the hotel.

ValuationRQ/OptionType

String

Indicates option types.

ValuationRQ/Nationality

String

Guest nationality (use ISO3166_1_alfa_2).

ValuationRQ/Rooms

Rooms in this option (room list).

Rooms/Room

1..n

@id

String

Room Identifier.

@roomCandidateRefId

Integer

Room candidate Identifier.

@code

String

Room code.

@description

String

Room description.

ValuationRQ/RoomCandidates

1..n

RoomCandidates/RoomCandidate

1..n

Room required.

@id

Integer

Id of requested room (starting at 1).

RoomCandidate/Paxes

1..n

Paxes/Pax

1..n

Pax required.

@age

Integer

Passenger age on the day of check-in.

@id

Integer

Passenger id (starting at 1).

ValuationRQ/Parameters

0..1

Additional parameters reported in AvailRS. If you receive parameters in AvailRS it is mandatory to send them exactly the same as received. If you don't send exactly the same parameters as received the Valuation could fail.

Parameters/Parameter

0..n

Additional parameter requiring integration.

@key

String

Contains keyword/Id to identify a parameter.

@value

String

Contains parameter value.

Valuation Response

After each request, the Seller will process the data and provide you with a response. Upon receiving a Valuation request, the Seller will send you a corresponding Valuation response.

The response options include either success or an error. In the event of success, the valuation response will provide you with updated information about the option you selected during the avail step.

Success

<ValuationRS xmlns:xsd = "http://www.w3.org/2001/XMLSchema" xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance">
   <Parameters>
      <Parameter key = "bd1" value = "43"/>
   </Parameters>
   <Status>OK</Status>
   <Price currency = "EUR" amount = "106.20" binding = "false" commission = "-1" minimumSellingPrice="-1"/>
   <CancelPenalties nonRefundable = "false">
      <CancelPenalty>
         <HoursBefore>72</HoursBefore>
         <Deadline>2016-07-01T05:00:00Z</Deadline>
         <CalculatedDeadline>false</CalculatedDeadline>
         <Penalty type = "Importe" paymentType = "MerchantPay" currency = "EUR">25.00</Penalty>
      </CancelPenalty>
      <CancelPenalty>
         <HoursBefore>48</HoursBefore>
         <Deadline>2016-07-02T05:00:00Z</Deadline>
         <CalculatedDeadline>false</CalculatedDeadline>
         <Penalty type = "Importe" paymentType = "MerchantPay" currency = "EUR">72.40</Penalty>
      </CancelPenalty>
   </CancelPenalties>
   <Fees>
      <Fee includedPriceOption = "true" description = "TaxAndServiceFee" mandatory = "true" refundable = "false">
         <Price currency = "EUR" amount = "8.11" binding = "false" commission = "-1" minimumSellingPrice="-1"/>
         <Code>SPE</Code>
      </Fee>
   </Fees>
   <Remarks/>
   <PaymentOptions cash = "false" bankAcct = "false">
      <Cards>
         <Card code = "VI"/>
         <Card code = "AX"/>
         <Card code = "CA"/>
      </Cards>
   </PaymentOptions>
   <CancelPoliciesDescription/>
</ValuationRS>

Success Response Data Breakdown

Element

Rel

Type

Description

ValuationRS

Root node.

ValuationRS/Parameters

0..1

Parameters for additional information.

Parameters/Parameter

1..n

List of parameters.

@key

String

Contains the keyword/Id to identify a parameter.

@value

String

Contains parameter value.

ValuationRS/Status

String

Status option (OK = available, RQ = on request).

ValuationRS/Price

Total price of this valuation.

@currency

String

Currency code (Our system uses a standard ISO - 3 for all suppliers).

@amount

Decimal

Option Amount.

@binding

Boolean

If binding is set as true, then the client can’t sell the product for a lower price that the one set by the supplier. If it set as as false, the client can sell the product for a lower price.

@commission

Decimal

Commission Scenarios

Commission	Description
0	The price returned is net.
-1	The supplier has not supplied the sale price nor the commission. This information is in the commercial contract with the supplier.
Greater than 0	X = % of the commission applied to the amount.

@minimumSellingPrice

Decimal

Indicates the minimum selling price it can be sold (determined by the Seller). If is specified (different than "-1"), that field takes preference to amount.

Minimum Selling Price vaScenarioslues

Minimum Selling Price	Description
0	No minimum selling price is provided.
-1	We have no information about MSP from the Seller.
Greater than 0	The lowest possible amount that can be sold commercially.

ValuationRS/CancelPenalties

Cancellation policy details.

@nonRefundable

Boolean

Indicate if this option is refundable or not.

CancelPenalties/CancelPenalty

0..n

Listing cancellation penalties.

CancelPenalty/HoursBefore

String

Number of hours prior to checkin date in which this Cancellation policy applies .

CancelPenalty/Deadline

String

Date on UTC Standard TimeZone in which this Cancellation policy applies (ISO 8601 e.g: 2016-07-01T05:00:00Z). Cancellation fees will be applicabled between this date and check-in date.

CancelPenalty/CalculatedDeadline

Boolean

Indicate if the Deadline is returned by the supplier or it's been calculated by Travelgate.If true, the deadline has been converted to UTC-0 by Travelgate. If False, the supplier returns the deadline on UTC-0, so no calculation is needed.

CancelPenalty/Penalty

Contains the value to be applied in net price.

@type

String

Types of penalties

Penalty	Description
Noches	Indicates the number of nights to be penalized.
Porcentaje	Indicates the percentage to pay based on the option price.
Importe	Indicates the exact amount payable.

@currency

String

Currency code (Our system uses a standard ISO - 3 for all suppliers).

@paymentType

String

Payment Types

Code	Description
MerchantPay	The payment is managed by the supplier.
LaterPay	The payment is managed by the hotel. The customer will use a credit-card as a guarantee for the hotel and the payment will be completed at check in.
CardBookingPay	The payment is managed by the supplier. The payment is effectuated at the time of booking.
CardCheckInPay	The payment is managed by the supplier. The payment is effectuated at check in in the hotel.

ValuationRS/Remarks

0..1

String

Remarks (see MetaData in order to verify if the supplier implements it).

ValuationRS/PaymentOptions

0..1

String

Payment Types allowed by the supplier. This tag is mandatory only if payment type is different than MerchantPay.

@cash

Boolean

Cash indicates whether payment will be made in cash (true) or by card (false).

@bankAcct

Boolean

BankAcct specifies whether payment will be made via bank transfer (true) or not (false).

PaymentOptions/Cards

0..1

List of cards allowed.

Cards/Card

1..n

@code

String

Credit Card codes

Code	Name
VI	Visa
AX	American Express
BC	BC Card
CA	MasterCard
CB	Carte Blanche
CU	China Union Pay
DS	Discover
DC	Diners Club
T	Carta Si
R	Carte Bleue
N	Dankort
L	Delta
E	Electron
JC	Japan Credit Bureau
TO	Maestro
S	Switch
EC	Electronic Cash
EU	EuroCard
TP	Universal air travel card
OP	optima
ER	Air Canada/RnRoute
XS	access
O	others

ValuationRS/Fees

0..1

Contains a list of fees.

Fees/Fee

1..n

@includedPriceOption

Boolean

Indicates if the fee is included or not in the final price (value indicated in the node Price in ValuationRS).

@description

String

Remarks regarding fee.

@mandatory

Boolean

If the fee is obligatory, depending on the includedPriceOption to know if it is paid at the time of booking or at the hotel. In case it is false, it could be a fee such as "cleaning" that the consumer could hire if he wanted.

@refundable

Boolean

This field will serve to know if the rate to be paid is returned, for example when it is a deposit type that is returned once the stay ends.

Fee/Code

String

Specifies the fee code in case it has one.

Fee/Price

@currency

String

Currency code (Our system uses a standard ISO - 3 for all suppliers).

@amount

Decimal

Fee Amount.

@binding

Boolean

If binding is set as true, then the client can’t sell the product for a lower price that the one set by the supplier. If it set as as false, the client can sell the product for a lower price.

@commission

Decimal

Commission Scenarios

Commission	Description
0	The price returned is net.
-1	The supplier has not supplied the sale price nor the commission. This information is in the commercial contract with the supplier.
Greater than 0	X = % of the commission applied to the amount.

@minimumSellingPrice

Decimal

Indicates the minimum selling price it can be sold (determined by the Seller). If is specified (different than "-1"), that field takes preference to amount.

Minimum Selling Price Scenarios

Minimum Selling Price	Description
0	No minimum selling price is provided.
-1	We have no information about MSP from the Seller.
Greater than 0	The lowest possible amount that can be sold commercially.

ValuationRS/CancelPoliciesDescription

0..1

String

Contains the cancellation penalties in free text (see MetaData in order to verify if the supplier implements it).

Error

<ValuationRS>
   <operationImplemented>true</operationImplemented>
   <applicationError>
      <code/>
      <type>204</type>
      <description>Supplier returns 0 results in availability.</description>
      <httpStatusCode>0</httpStatusCode>
   </applicationError>
</ValuationRS>

Error types that will be included in the response in the event of an error

Error Type	Error Description	Comments
101	System Exception.	Exception not controlled or not classified as general exception.
102	Provider Error.	Seller returns a particular code/description for an error, which is then transmitted to you in our response.
103	Too many requests to the supplier.	Your account has surpassed the agreed-upon request limit with the Seller.
104	Connection Timeout With Provider.	The Seller's response time has exceeded the timeout set in the Buyer's request.
105	Communication Error.	The connection to the Seller has been refused (we haven't been able to connect to their system).
105	Payload too high.	The size of the response by the Seller surpasses the size limitation established on our side for optimal performance (20000 options or 15MB).
204	No results found.	Seller does not return any results for the specific availability criteria set in the Buyer's request (e.g. hotel, dates, market, etc.).
205	Room Candidate Not Supported.	The number of room candidates in your request exceeds the maximum set by the Seller.
206	Dates Not Supported.	Your availability request does not align with the Seller's date specifications.
207	Request XML not accepted by Supplier.	Your availability request does not align with the Seller's specifications.
301	Option Not Found In Valuation.	Seller fails to return the option previously chosen by the Buyer in Search response (the option is no longer available). This error can be encountered in Quote response and Book response (whenever the integration requires an additional Quote to the Seller).
302	Hotel not found.	Our system is unable to locate the hotel you requested in your Hotels (DescriptiveInfo) method
303	Booking not confirmed.	Seller hasn't been able to confirm a booking for some reason (is not very common and might be returned in reservation response).

Valuation Request​

Request Data Breakdown​

Valuation Response​

Success​

Success Response Data Breakdown​

Error​

Valuation Request

Request Data Breakdown

Valuation Response

Success

Success Response Data Breakdown

Error