Creating Hotel Bookings

Hotel booking creates a hotel reservation based on the room and rate results from a Hotel Rate and Rule Search response.

Schema

See the Hotel Booking transactions in HotelReqRsp.xsd:

Request

HotelCreateReservationReq is used to create hotel bookings.

Minimum Required Data

A hotel segment can be booked only if it is part of a PNR that contains passenger and booking data for a complete trip, including one or more travel segments (air, car, hotel, or rail). If a reference to an existing Universal Record is indicated, the hotel segment is added to the PNR. If no Universal Record exists for this booking, a new PNR is created. 

In addition to the baseline data required for a PNR, additional data is required specifically for a hotel reservation. Unless otherwise noted, all of the elements are direct children of HotelCreateReservationReq.

Notes:

 

 

Element/Attribute

Description

BookingTraveler

If a new Universal Record and PNR must be created for the hotel booking, Booking Traveler information must be included. If the hotel booking is being added to an existing Universal Record, the UR must be retrieved and modified to add a hotel booking.

For Hotel reservations, a primary traveler's name and phone number are required. Any additional BookingTraveler data is optional.

BookingTraveler/AppliedProfile can be used to indicate the Profile data applied to this transaction.

HotelRateDetail

These required HotelRateDetail attributes are returned in the Detailed Hotel Search results:

  • RatePlanType, which is the booking code that identifies the room type and associated rate.

  • The Base booking rate, without additional taxes or fees.

While the following attributes are not required, they are recommended for best practice:

  • Any associated Tax rates.

  • The Total amount of the booking, which combines base rates and taxes.

HotelProperty

These required HotelProperty attributes are returned in the Detailed Hotel Search results:

  • HotelChain, which is the hotel supplier code.

  • HotelCode, which is the unique identifier for the hotel property.

  • HotelLocation,which is the three-character city code that is used to cross-check the HotelCode.

HotelStay

Indicates the check-in and check-out dates for the hotel booking.

Number of Adults

The number of adults in the booking request.

Note: It is not possible to book several rooms with different rate, occupancy, or check-in and check-out dates, in the same HotelCreateReservation request.

Number of Rooms

Multiple rooms can be added to the booking request.

Note: It is not possible to book several rooms with different rate, occupancy, or check-in and check-out dates, in the same HotelCreateReservation request. If multiple rooms are added using NumberOfRooms, they are booked with identical parameters.

Optional Request Data

Optional data can also be sent to further refine the request.

 

Element/Attribute

Description
@MandatoryRateMatch

The Hotel Rate Match indicator allows the Booking response to indicate if there is a discrepancy between the hotel rate data sent in the Hotel Booking request and the rate data returned in the Booking response.
RetrieveProviderReservationDetails

RetrieveProviderReservationDetails is a Boolean attribute.

  • When set to false (default), the response displays provider details using UniversalRecord/ProviderReservationInfo/ProviderReservationDetails.
  • When set to true, ProviderReservationDisplayDetailsList displays in the response in UniversalRecord/ProviderReservationInfo. This element displays some details of the PNR elements that are not otherwise returned in the Universal Record.

Universal versions prior to v29.0 will not return the ProviderReservationDisplayDetailsList element.

BookingSource

Intended for internal use. Do not use unless directed to by your account manager.

The content can be alpha, numeric, or alpha/numeric and can be any number of characters. Galileo does not require differentiation between Pseudo City Code and IATA number. Worldspan does require differentiation between Pseudo City Code and IATA number.

Note: No validation occurs for this data.

Authorized By

Indicates who is creating or modifying the Universal Record.

In agency applications, the Authorized data is typically the booking agent. In consumer applications, this data is typically a programmatically generated indicator of the travel provider.

RuleName

Universal API supports attaching a mandatory Custom Check rule when a request to create a reservation has a Custom Check rule name, using the RuleName attribute. RuleName supports up to 10 alphanumeric characters (no special characters) and the attachment of a Custom Check rule name in the booking request. If Custom Check rule is attached to a reservation, the rule is captured in the Universal Record History.

Note: The user must know the name of the rule to attach to the booking.

See @CustomCheck in the response on this page in ProviderReservationInfo.

UniversalRecordLocatorCode

The Universal Record Locator (UR) is an identifier for the entire booking associated with this trip, which can include multiple booking segments and data from external sources.

For the initial booking, no UR exists.

BookingTraveler

While the traveler's name and phone number are required, additional traveler-related data is optional:

Booking modifiers for hotel reservations include:

  • Email address

  • Loyalty Programs

  • General Remarks

BookingTraveler may be included multiple times in a request that includes more than one traveler.

Notes:

  • The first instance of BookingTraveler is deemed Primary in the BookingTravelerRef element in the response.

  • Multiple loyalty cards are supported in a passive book when they are different types. If multiple cards of the same type are provided, only the first loyalty card of that type is sent, and a warning message is returned.

SSR

Optionally, @ProfileID and @ProfileSecureFlightDocKey can be included in the request for DOCO, DOCA, or DOCS SSRs (Special Service Requests). Universal API validates the TravelerID in BookingTraveler/AppliedProfile against the Universal Record and the Air Booking request that is being sent. The ProfileSecureFlightDocKey is not validated.

Both ProfileID or ProfileSecureFlightDocKey must be sent in the request for secure flight SSRs or an error is returned.

See the response for more details.

HotelSpecialRequest

Special request can be used for additional information sent to the supplier (hotel chain).

Guarantee

Indicates whether a guarantee or deposit is required as an advance payment type for the selected a hotel booking code (RatePlanType).

Guarantees, deposits, or pre-payments are payments that may be required to reserve a hotel booking in advance of the hotel stay. These rates must be booked with a deposit. Do not book these rates improperly with guarantee or passing prepayment, as this results in booking failures. For example, passing the value HotelCreateReservationReq/Guarantee/@Type as "PrePayment" returns an error "Guarantee @Type Prepayment not supported."

  • Guarantee

    A charge is not made to the credit card. Rather, the card number is held against a cancellation that violates the hotel's cancellation policy.

  • Deposit

    Credit Card: A charge is made to the credit card (typically one night's stay). If the booking is canceled, the deposit is forfeited to the supplier.

    Check: Travelport Universal API has standardized the handling of deposits with a check form of payment for hotel reservations in Worldspan (1P), Galileo (1G), and Apollo (1V). In both the request and response, when a check is used as a deposit, data is sent and returned in the Guarantee element:

    <Guarantee Type="Deposit" >

    <OtherGuaranteeInfo Type="Deposit Taken">CHECK</OtherGuaranteeInfo>

    </Guarantee>

  • Pre-Payment

    Requires payment at the time of booking for part or all of the hotel stay at the time of booking.

    If the booking is canceled, the amount or availability of a refund varies according to the rules associated with the specified booking code (RatePlanType).

Some hotels do not require a credit card guarantee or deposit. Typically, these hotels will guarantee the room for a specific arrival time, such as 6:00 PM. If the traveler does not check in by the guarantee time, the room will not be held for them.

GuestInformation

Specifies the number and type of travelers (adult or child) in the booking. Can be used to add fees for additional children.

ReviewBooking

Review Bookings (Q-Minders) are a provider functionality that issues reminders to agents for any pending tasks that must be done by a specific date and time. The PNR and the reminders are put into the Agency Queue on the date and time specified in Review Booking.

HotelCommission

A HotelCommission element allows hotel commission to be added to a booking and then updated or deleted with UR Modify.

This enhancement is supported by Worldspan (1P).

OverridePCC

Note: Refer to Emulation for more information.

The OverridePCC is used to specify the emulated PCC in Common.xsd. When the Override PCC is sent in a booking request:

  • The OwningPCC attribute in ProviderReservationInfo is set to the emulated PCC (the OverridePCC).
  • For Worldspan , the Override PCC is used to set the PCC in the first phone field of the provider PNR, therefore making the OverridePCC the Owning PCC of the PNR.
  • For Galileo and Apollo, Service Bureau set up is required for emulation with Override PCC.

If OverridePCC is NOT sent in the booking request, the OwningPCC attribute in ProviderReservationInfo is set to the Target Branch.
Book on Book

Air, hotel, vehicle, and passive Book on Book is allowed to append itinerary content in the same provider PNR if the PNR's owning PCC has a host bridge branch relationship with the Override PCC or PCC of the Target Branch in the request. The emulating PCC and owning PCC must have host bridge branch relationship so that the PNR can be retrieved and can be modified in the host.

Book on Book for a Hotel Create Reservation request is allowed with host Provider Locator Code and Universal Record Locator Code.
AgentIDOverride

AgentIDOverride in the request overrides any default agent sine placed in the PNR. This is a two-character alphanumeric code of the agent sine that should replace the default. The AgentOverride attribute is returned in the response, noted below in Provider Reservation Info. The agent sine cannot be updated after the PNR has been finalized.

With the agent sine override, the Universal Record is updated with the override action. If the agent sine is not present in the request, Universal API places the default agent sine in the PNR header. If the agent sine has an invalid value, Universal API continues with the booking and provides the warning "Agent ID is invalid and override is ignored."

CommissionIndicatorRelease 19.1

The CommissionIndicator allows the commission content to be returned in the sold hotel segment so that the middle office, back office, and third party commission partner can track the commission. The Hotel Commission indicator returns in /UniversalRecord/HotelReservation//BaseHotelReservationGroup as part of:

  • UniversalRecordRetrieveRsp
  • UniversalRecordImportRsp
Email (per segment for both Traveler and Agency) Release 22.2

Universal API 22.2.2 and greater provides the ability to add traveler and agency email addresses at the hotel segment level, at the time of booking, so that third party billing applications, e.g., Nightbridge, can properly bill agencies in the event of a no-show.

HotelCreateReservationReq/

@Email Type="Traveler" EmailID="123@456.com"

@Email Type="Agency" EmailID="ABC@XYZ.com"

Response

The booking response is returned in HotelCreateReservationRsp.

A basic Hotel Reservation response includes the Universal Record, as well as the Hotel Reservation information for this booking in the HotelReservation element.

ARNK (Arrival Unknown) segments are added to the host PNR automatically wherever required, particularly for continuity breaks with the provider PNR. ARNK (Arrival Unknown) segments that are present in Galileo and Apollo provider PNRs are included in the response in the ProviderARNKSegment, to allow agents to view the exact provider PNR composition.

/ProviderReservationDetails @CustomCheck

@CustomCheck is set to "true" if a PNR has a Custom Check attached in the Galileo or Apollo provider reservation that was imported via Universal API.

The Custom Check rule name is returned in the detailed display of the Provider Reservation, or if it is not found, a message is returned: Custom Check not found.

If creation of the background passive fails on the provider (for example, a RuleName is not attached to a PNR or there is non-compliance with an attached RuleName), a Universal Record is created successfully, with a provider locator of ACH or SDK, as appropriate.

If a Pseudo City Code (PCC) has a mandatory Custom Check rule that was attached during reservation creation, and the attached rule is compliant, a background passive is successfully created on the Galileo or Apollo provider, and the reservation is also successfully created in Universal API.

Note: The Universal Record History Search response (UniversalRecordHistorySearchRsp) will have a custom check rule name if one was attached to a new PNR in a reservation. Universal Record History only captures the RuleName if the rule name was valid and a reservation was successfully created.

@AgentOverride

If the request included the optional AgentIDOverride attribute, the AgentOverride attribute returns the agent sine used to override the default agent sine.

If a Traveler name is more than 55 characters, the secure flight SSR is displayed at the Universal Record level and not at the Booking Traveler level. This means that when SSR @ProfileID and @ProfileSecureFlightDocKey are sent in the request, they are returned in the response at either:

  • The Booking Traveler level: 
  • HotelCreateReservationRsp/UniversalRecord/BookingTraveler/SSR @ProfileSecureFlightDocKey
  • HotelCreateReservationRsp/UniversalRecord/BookingTraveler/SSR @ProfileID
  • The Universal Record level:
  • HotelCreateReservationRsp/UniversalRecord/SSR @ProfileSecureFlightDocKey
  • HotelCreateReservationRsp/UniversalRecord/SSR @ProfileID

After SSRs are added successfully with the Traveler ProfileID and ProfileSecureFlightDocKey and the UR is finalized, the UR displays the ProfileID and ProfileSecureFlightDocKey that is associated to SSR DOCS/DOCO/DOCA.

  • If ProfileID and ProfileSecureFlightDocKey are present in SSRs other than DOCO/DOCA/DOCS, Universal API returns an error: "Profile ID and ProfileSecureFlightDocKey only valid for SSR DOCA/DOCO/DOCS".
  • Universal API validates the Traveler Profile ID (BookingTraveler/AppliedProfile/@TravelerID) against the Universal Record and the Air Booking request that is being sent. If there is no match, an error is returned: "Profile ID specified in SSR is not present in Booking traveler(s) in request or Universal Record"
  • Both ProfileID and ProfileSecureFlightDocKey must be sent in the request or an error is returned: "Profile ID or ProfileSecureFlightDocKey must be accompanied with each other for Secure Flight SSRs".

The HotelReservation element occurs in one of two places, depending on how the Universal setting was made in the request:

  • If UniversalRecord was set to 'false' in the request, the hotel reservation information for this booking is returned in the HotelReservation child element of HotelCreateReservationRsp. Only data from this specific booking is returned in the response.

  • If UniversalRecord was set to 'true' in the request, the hotel reservation information for this booking is returned in UniversalRecord/HotelReservation, as well as data from any other bookings included in this Universal Record.

A basic booking request typically returns a HotelReservation response with hotel property information, room/rate descriptions, and booking rate data.

The LocatorCode attribute of HotelReservation represents the confirmation code provided by the booking supplier, and is distinct from the LocatorCode of UniversalRecord, which represents all combined bookings in the overall record.

The BookingTravelerRef may contain one or more passengers, in the case of a multi-passenger booking. The first traveler entered, against whom the reservation is made, is contained in the Primary element.

The HotelProperty elements returns address and contact information for the hotel property. If available, the distance and direction from the requested city center or reference point is also included.

As of release 17.1, the long form of the property name is returned in mixed case, rather than the short form in upper case. For example, DBLTREE TALLAHASSEE is returned as Doubletree By Hilton Tallahassee. If the long form of the name is unavailable, the short form is returned.

This enhancement applies only to Galileo (1G) and Apollo (1V).

The HotelRateDetail returns the Rate Plan Type (booking code) and base, tax, and total rates for the booking.

Rate and room descriptions in RoomRateDescription were added to Hotel Booking as a configurable option. By default, Universal API returns room/rate description text in Hotel Booking responses. However, this functionality is configurable by Target Branch. Contact your Travelport representative if you want to request that room/rate descriptions be disabled for Hotel Booking responses for a specific Target Branch.

The dates for the complete booking period are noted in HotelStay.

If a credit card or other form of payment was used in the request for a deposit, guarantee, or pre-payment, a Guarantee element is present, if discrete Guarantee data is supported by the provider and supplier.

If BookingSource was sent in the request, the response contains the three characters "AGT", followed by up to a maximum of eight characters.

A SellMessage may be present if the supplier (vendor) returns one. Sell Messages are tied to segment/reservation and if the segment/reservation is deleted then corresponding messages will also be deleted.

The Hotel Rate Match indicator in the request (@MandatoryRateMatch) allows the Booking response to indicate if there is a discrepancy between the hotel rate data sent in the Hotel Booking request and the rate data returned in the Booking response. HotelRateChangedInfo provides the rate details returned by the supplier in the Booking response if there is a rate discrepancy.

Exceptions

  • Universal API does not have a discrete equivalent to an end transact (PNRBFEnd). When a created, modified or canceled booking is submitted, Universal API internally processes the end transact as part of the request. There is also no equivalent functionality to PNRBFIgnore.

  • HotelSpecialRequest

    • Limited to 80 characters.

    • Cannot contain the slash character in the request / on Apollo and Galileo.

    • The error T541 INVALID CHARACTER IN OPTIONAL DATA FIELD- SI returns due to the slash character in the request.

  • When the first 15 characters of a last name/first name combination match another last name/first name combination in the same PNR, the names are sent to the Galileo host in the booking request as a cluster of names, with an allowed cumulative total of 55 characters for first name, prefix, last name, and suffix.

    For example: A PNR with these two passengers:

    Salomonowicz/Barbara

    Salomonowicz/Bartholomew

    • Is clustered because the first 15 characters are the same: Salomonowicz/Ba

  • HotelCommission is not supported.

  • Some suppliers return informational messages or validation messages as advisory text which does not follow a specific format and differs across suppliers. In Universal API, this text is returned as a warning message in the response.

  • If available, Worldspan returns text in HotelRateDetail/RoomRateDescription. Possible RoomRateDescription values are: Room, Rate, Extra Charges, Packages, Room Detail, Miscellaneous, and Description. Multiple text attributes may be included.

  • Worldspan does not support PointOfSale in the request. Any value provided is ignored, and a warning is sent in the response: "Separate PointOfSale not supported by provider".

  • Worldspan does not support Review Bookings.

  • Worldspan does not supported HotelRateDetails/CancelInfo. Worldspan continues to support non-refundable or cancellation information provided by the supplier in their Integrated Source functionality. In Travelport Universal API, this information is returned in the Hotel Rate and Rules Search response in HotelDetails Rsp/RequestedHotelDetails/HotelRateDetail/RoomRateDescription, where @Name=”Cancel Policy” or “Cancellation”.