Add Hotel Reservation Reference Payload API Reference
|
Put |
book/reservations/{AggregatorLocatorCode} For {LocatorCode} send the locator code returned at booking commit or in Reservation Retrieve in Receipt/Confirmation/Locator/value. Base path: Pre-production https://api.pp.travelport.net/11/hotel/ Production https://api.travelport.net/11/hotel/ Travelport has updated all JSON API authentication and authorization endpoints. The previous production endpoints will be deprecated 30 Jan 2026. Pre-production endpoints were deprecated 5 Dec 2025. See Endpoint Migration for details.
|
Related Content: JSON Hotel APIs Guide, Hotel Workflows, Hotel Availability API Reference
Add Hotel Reservation allows you to add another hotel room to an existing reservation, This reference payload request sends a cached offer ID from a preceding Availability response. It requires both a preceding search (either by location or by ID) request and an Availability request, or a SearchComplete request.
As an alternative, you can send full offer details in the Add Hotel Reservation full payload request.
Multi-room sell requests
When making a reservation, Travelport attempts to sell the number of rooms requested; however, the supplier may not be able to accommodate the total number of rooms. Each room sold creates a unique hotel segment on the Travelport reservation. A traveler name is associated with each room with these limitations:
-
If the number of rooms requested is equal to the number of traveler names in the request, each room is associated with a unique traveler name.
-
If the number of rooms requested is not equal to the number of traveler names in the request, all rooms are associated with the first traveler name.
Request
Query Parameters
Hotel APIs that create a new reservation or add a new segment to an existing reservation verify the reservation request with the guarantee type and price returned in preceding steps in the workflow (either theAvailability or SearchComplete.response.) When there is any difference, the API does not yet create the reservation but instead returns an error to notify about the change. To accept the change, send the request a second time with the applicable query parameter/s below. Do not send either of these query parameters in the initial request.
If you do not want to proceed with the booking because of the changes, you are not required to send a second booking request with the false value/s per below. You can simply let these offers expire.
| Object | Description |
|---|---|
|
acceptPriceChangeInd |
Boolean. Send with true to accept any difference in the current sell price from the total price returned in an earlier response. Default is false; terminates the sell process without booking. |
|
acceptGuaranteeChangeInd |
Boolean. Send with true to accept any difference in the guarantee type from the guarantee type returned in an earlier response. (The guarantee types checked for differences are guarantee required, deposit required, prepay required.) Default is false; terminates the sell process without booking. |
Request Body
ReservationDetail*
Top level object for the request.
Includes the Offer, Receipt, FormOfPayment, Payment, ReservationComment, and TravelAgency objects.
Offer*
ID of the offer to add to the booking.
id* : String. Offer identifier for the offer to add. Send the value from the response returned earlier in the workflow, either Availability or SearchComplete:
Availability: Send the value returned in CatalogOffering/id for the instance of CatalogOffering for the offer to add.
SearchComplete: Send the value returned in propertyItems/lowestPublicAvailableRate/rateKey/value for the instance of propertyItems to add.
FormOfPayment object
FormOfPayment*
Top level object for form of payment details. Includes PaymentCard object.
PaymentCard*
Form of payment details.
expireDate*: String. Credit card expiration date in MMYY format.
CardType*: String. Type of card; supported values are Credit, Debit, Gift.
CardCode* : String. Code for credit card type.
CardHolderName*: String. Name on credit card.
Includes CardNumber, SeriesCode, Telephone, and Address objects.
CardNumber*
Card number details.
PlainText*: String. Credit card number.
SeriesCode
Security code of card.
PlainText* for certain suppliers: String. The credit card three- or four-digit CVV code.
Booking.com requires the CVV code.
Telephone
Telephone information associated with card.
countryAccessCode: String. Phone country code.
phoneNumber: String. Phone number.
areaCityCode: String. Phone local area code.
cityCode: String. Agency city code.
Address
Billing address details. Includes Number, Street, AddressLine, City, StateProv, Country, and PostalCode objects.
Number
Top level object for street number of billing address.
value: String. Street number value.
Street
String. Street name.
AddressLine
String. Address number and street name.
City
String. The city of the billing address.
County
String. The county of the billing address.
StateProv
Top level state or province object.
value: String. State or province of billing address.
name: String. Full state or province name.
Country
Country of billing address.
Value: String. Standard two-letter coded value for country.
Id: String. Custom user-assigned identifier for the country.
Name: String. Full country name.
codeContext: String. Organization that provided the Id number.
PostalCode
String. Postal code of billing address.
Billing email address.
value: String. Billing email address.
Payment and TravelAgency
Payment*
Top level object for payment details.
The amount to be charged for the hotel reservation as follows:
-
For Prepay Required rates, the full total amount is used. This amount will be charged to the credit card on this transaction. Indicators should be set as: depositInd = true; guaranteeInd = false.
-
For Deposit Required rates, the deposit amount is used. This amount will be charged to the credit card on this transaction. Indicators should be set as: depositInd = true; guaranteeInd = false.
-
For Guarantee Required rates, the full total amount is used. This amount is expected to be charged to the credit card at check in. Indicators should be set as: depositInd = false; guaranteeInd = true.
id: String. Customer-assigned identifier for the payment.
PaymentRef: String. Customer-assigned name for the payment.
depositInd*: Boolean (true/false). If set to true, at booking, credit card is charged for deposit or prepay rate.
guaranteeInd*: Boolean (true/false). If set to true, no amounts are charged at booking; customer is to make payment at check in at the hotel.
Includes Amount object.
Amount*
Amount of payment.
code*: String. Currency code.
value*: String. Amount to pay.
TravelAgency
Optional top level object for travel agency information. Includes AgencyPCC and Telephone objects.
AgencyPCC
Top level object.
agencyCode: String. Agency PCC code.
Telephone
Top level object for agency telephone information.
phoneNumber: String. Agency telephone number.
areaCityCode: String. Agency phone local area code.
phoneUseType: String. Agency code for how phone is used. (e.g., Home, Business, Emergency Contact, Travel Arranger, Day, Evening)
cityCode: String. Agency city code.
Traveler object
Traveler*
Traveler details.
Includes PersonName, Telephone, Email, and CustomerLoyalty objects.
PersonName*
Traveler details.
Given*: String. Traveler first name.
Surname*: String. Traveler last name.
Prefix: String. Salutation of honorific (e.g. Mr., Mrs., Ms., Miss, Dr.)
Telephone*
Traveler telephone details.
countryAccessCode: String. Phone country code.
phoneNumber*: String. Phone number.
areaCityCode*: String. Phone local area code.
cityCode: String. Phone city code.
Email*: for certain suppliers
Traveler email address.
value*: String. Traveler email address.
CustomerLoyalty
One frequent guest number and / or one frequent flyer number.
programId* if object used: String. Two character hotel or air supplier code or brand code of the loyalty program.
value* if object used: String. Number on loyalty card.
supplierType* if object used: String. Send with hotel to designate number as frequent guest or air to designate as frequent flyer.
ReservationComment object
The following objects noted as required* are required only if ReservationComment is sent.
ReservationComment
Optional top level object for remarks. See Comments and Remarks in the JSON Hotel APIs Guide for more about remarks.
commentSource*: Originator of comment. Supported value is Agency.
shareWith*: Designates visibility of remark. Send the following for each type of remark:
Notepad remarks: Agency
Unassociated remarks: Traveler
Special instructions: Supplier
Includes Comment object.
Comment*
Array of name/value pairs.
name*: Type of remark. Send the following for each type of remark:
Notepad remarks: Two-character code. Use asterisk for any placeholder. (HS, CR, R*, **)
Unassociated remarks: ITIN COMMENTS
Special instruction remarks: SI
value*: String. Remark text. Character limits for each type of remark:
Notepad remarks: 87
Unassociated remarks: 70
Special instruction remarks: 50
Accounting
Optional top level object used for all DOCI remarks.
dataType*: Accounting remark designator. Accepted value: DOCI.
Includes NameValuePair object.
NameValuePair*
Array of name/value pairs.
name* : Type of remark. Supported values and meanings:
DYO Design Your Own Itinerary FS Fare Saver CR Canned Remarks TK Ticket Number Details AC Agent, Account, or Branch Details AR Replace Sign On Code X* Back Office Accounting Details FT Free Text
value*: String. Text to pair with name values above. Note the following character limits for each name value:
DYO 2 digit, numeric FS 9 characters total limit in format 1 (all numeric) or format 2 (numeric “–“ two alpha) CR 42 characters total limit in format (two numeric “.” two numeric “.” etc) TK 8 to 12 characters in format 1 (all numeric) or format 2 (numeric “-“ three numeric) AC 42 characters, alphanumeric and some special characters AR 10 characters, alphanumeric X* 84 characters, alphanumeric and some special characters FT 84 characters, alphanumeric and some special characters
Example request body
"ReservationDetail": {
"Offer": [
{
"@type": "Offer",
"id": "62b3ced3-92f7-47b3-adb1-03588c5dc5a7:190000fa-366c-4ffd-a4d1-59d17177c774"
}
],
"Payment": [
{
"@type": "Payment",
"Amount": {
"code": "USD",
"value": 308.43
}
}
],
"FormOfPayment": [
{
"@type": "FormOfPaymentPaymentCard",
"PaymentCard": {
"@type": "PaymentCardDetail",
"expireDate": "0825",
"CardType": "Credit",
"CardCode": "VI",
"CardHolderName": "Frank Sinatra",
"CardNumber": {
"@type": "CardNumber",
"PlainText": "XXXXXXXXXXX"
},
"SeriesCode": {
"@type": "SeriesCode",
"PlainText": "XXX"
},
"PersonName": {
"@type": "PersonNameDetail",
"Given": "Bill",
"Surname": "Thisguy"
},
"Address": {
"@type": "AddressDetail",
"Number": {
"value": "125"
},
"Street": "Billing Address Street",
"AddressLine": [
"125 Billing Address Street"
],
"City": "Claremont",
"County": "Los Angeles",
"StateProv": {
"value": "CA"
},
"Country": {
"value": "US"
},
"PostalCode": "91711-3323"
},
"Telephone": [
{
"@type": "TelephoneDetail",
"countryAccessCode": "1",
"areaCityCode": "909",
"phoneNumber": "1231234",
"cityCode": "DEN"
}
],
"Email": [
{
"value": "smith@example.com"
}
]
}
}
],
"Traveler": [
{
"@type": "Traveler",
"PersonName": {
"@type": "PersonName",
"Given": "Jon",
"Surname": "Smith",
"Title": "Mr"
},
"Telephone": [
{
"@type": "TelephoneDetail",
"countryAccessCode": "91",
"areaCityCode": "011",
"phoneNumber": "9891766469",
"cityCode": "DL"
}
],
"Email": [
{
"value": "smith@example.com"
}
]
}
]
}
}Response
The Hotel Add Reservation response returns the same data in the same structure as does Create Reservation. See the Create Reservation API Reference for documentation. See below for an example.
The Add Reservation reference payload response returns details for only the reservation added, not the reservation already on the booking. For full reservation details including all segments, send a Reservation Retrieve request after adding another room.
The response for both the Add Reservation reference payload and full payload responses are identical with the exception of the Reservation/id object, which is returned per below only for the reference payload response. Reservation/id returns the offer identifier sent in the reference payload request.
Example
Show Example
{
"ReservationResponse": {
"Reservation": {
"@type": "ReservationDetail",
"id": "f1ecd79d-198c-4fe3-ae91-a9ca9cd10637",
"Offer": [
{
"@type": "Offer",
"Identifier": {
"authority": "BKNG"
},
"Product": [
{
"@type": "ProductHospitality",
"Quantity": 1,
"bookingCode": "147245306_307884210_1_1_0",
"guests": 1,
"PropertyKey": {
"chainCode": "CN",
"propertyCode": "B6381"
},
"RoomType": {
"@type": "RoomTypeDetail",
"RoomCharacteristics": {
"smokingAllowed": "No",
"wifiIncluded": "No",
"BedConfiguration": [
{
"quantity": 2,
"bedType": "Large double bed(s)",
"size": "151-180cm wide"
}
]
},
"Description": {
"value": "Double Queen Deluxe Room. This room is equipped with two queen-sized bed and smart controls with a flat-screen satellite TV and a minibar. It also has five-fixture bathroom boasts a walk-in shower and separate bathtub with in-mirror television. Other amenities include an in-room safe, iron/ironing board and individual controlled air-conditioning."
},
"RoomAmenity": [
{
"description": "Tea/Coffee maker"
},
{
"description": "Minibar"
},
{
"description": "Key card access"
}
],
"RoomOccupancy": [
{
"maxOccupancy": 1
}
]
},
"DateRange": {
"start": "2022-02-22",
"end": "2022-02-25"
}
}
],
"Price": {
"@type": "PriceDetail",
"CurrencyCode": {
"value": "USD",
"decimalPlace": 2
},
"TotalPrice": 150,
"TotalTaxes": 50,
"TotalFees": 30,
"Base": 100,
"PriceBreakdown": [
{
"@type": "PriceBreakdownHospitality",
"roomPricingType": "Per night",
"NightlyRate": [
{
"startDate": "2022-02-22",
"nights": 1,
"Amount": {
"CurrencyCode": {
"value": "USD"
},
"Base": 40,
"Total": 60,
"Taxes": {
"@type": "TaxesDetail",
"TotalTaxes": 20,
"Tax": [
{
"currencyCode": "USD",
"taxCode": "CITYTAX",
"Description": "Tax and Service fee",
"includedInBase": "No",
"value": 16
},
{
"currencyCode": "USD",
"taxCode": "VAT",
"Description": "VAT",
"includedInBase": "No",
"value": 4
}
]
}
}
},
{
"startDate": "2022-02-23",
"nights": 3,
"Amount": {
"CurrencyCode": {
"value": "USD"
},
"Base": 60,
"Total": 90,
"Taxes": {
"@type": "TaxesDetail",
"TotalTaxes": 30,
"Tax": [
{
"currencyCode": "USD",
"taxCode": "CITYTAX",
"Description": "Tax and Service fee",
"includedInBase": "No",
"value": 24
},
{
"currencyCode": "USD",
"taxCode": "VAT",
"Description": "VAT",
"includedInBase": "No",
"value": 6
}
]
}
}
},
{
"startDate": "2022-02-26",
"nights": 1,
"Amount": {
"CurrencyCode": {
"value": "USD"
},
"Base": 60,
"Total": 90,
"Taxes": {
"@type": "TaxesDetail",
"TotalTaxes": 30,
"Tax": [
{
"currencyCode": "USD",
"taxCode": "CITYTAX",
"Description": "Tax and Service fee",
"includedInBase": "No",
"value": 24
},
{
"currencyCode": "USD",
"taxCode": "VAT",
"Description": "VAT",
"includedInBase": "No",
"value": 6
}
]
}
}
}
],
"AverageNightlyRate": [
{
"code": "USD",
"value": 50,
"approximateInd": true
}
],
"AmenitySurcharges": {
"@type": "AmenitySurchargesDetail",
"Surcharge": [
{
"currencyCode": "USD",
"description": "Crib Surcharge",
"value": 0
},
{
"currencyCode": "USD",
"description": "Rollaway Surcharge",
"value": 25
}
]
}
},
{
"@type": "PriceBreakdownHospitality",
"roomPricingType": "Per stay",
"Amount": {
"CurrencyCode": {
"value": "USD"
},
"Base": 100,
"Total": 150,
"Taxes": {
"@type": "TaxesDetail",
"TotalTaxes": 50,
"Tax": [
{
"currencyCode": "USD",
"taxCode": "CITYTAX",
"Description": "Tax and Service fee",
"includedInBase": "No",
"value": 40
},
{
"currencyCode": "USD",
"taxCode": "VAT",
"Description": "VAT",
"includedInBase": "No",
"value": 10
}
]
},
"Fees": {
"@type": "FeesDetail",
"TotalFees": 30,
"Fee": [
{
"feeCode": "RESORT",
"feeApplication": "PerAccommodation",
"feeFrequency": "PerStay",
"FeeAmountOrPercent": {
"Amount": {
"code": "USD",
"value": 15
}
}
}
]
},
"Commission": {
"@type": "CommissionAmount",
"application": "Non-paying "
},
"Description": "Standard Double or Twin Room - Free cancellation - Free WiFi"
}
}
]
},
"TermsAndConditionsFull": [
{
"@type": "TermsAndConditionsFullHospitality",
"Guarantee": [
{
"GuaranteeType": "PrepayRequired"
}
],
"CancelPenalty": [
{
"Deadline": {
"SpecificDate": {
"start": "2022-01-19",
"end": "2022-02-14"
},
"Time": "23:59:59.000"
},
"HotelPenalty": {
"@type": "HotelPenaltyAmount",
"Amount": [
{
"value": 0,
"code": "INR"
}
]
},
"Refundable": "Yes"
},
{
"Deadline": {
"SpecificDate": {
"start": "2022-02-15",
"end": "9999-12-31"
},
"Time": "23:59:59.000"
},
"HotelPenalty": {
"@type": "HotelPenaltyAmount",
"Amount": [
{
"value": 9000,
"code": "INR"
}
]
}
}
],
"MealsIncluded": {
"breakfastInd": true,
"lunchInd": false,
"dinnerInd": false
},
"ProductRateCodeInfo": [
{
"RateCodeInfo": {}
}
]
}
]
}
],
"Traveler": [
{
"@type": "Traveler",
"id": "T1",
"PersonName": {
"Given": "John",
"Surname": "Smith"
},
"Telephone": [
{
"countryAccessCode": "1",
"areaCityCode": "909",
"phoneNumber": "1231234",
"cityCode": "DEN"
}
],
"Email": [
{
"value": "smith@example.com"
}
]
}
],
"TravelerProduct": [
{
"@type": "TravelerProduct",
"TravelerRef": "T1",
"OfferRef": "O1"
}
],
"Payment": [
{
"Amount": {
"value": 143,
"code": "GBP"
}
}
],
"Receipt": [
{
"@type": "ReceiptConfirmation",
"OfferRef": [
"O1"
],
"Confirmation": {
"@type": "ConfirmationHold",
"confirmationStatus": {
"@type": "OfferStatusHospitality",
"Status": "Confirmed"
},
"Locator": {
"value": "T9RY0-WQ842",
"locatorType": "Confirmation Number",
"source": "BO",
"sourceContext": "Supplier"
},
"OfferStatus": {
"@type": "OfferStatusHospitality",
"Status": "Confirmed"
}
}
},
{
"@type": "ReceiptConfirmation",
"OfferRef": [
"O1"
],
"Confirmation": {
"@type": "ConfirmationHold",
"Locator": {
"value": "4619",
"locatorType": "Pin code",
"source": "BO",
"sourceContext": "Supplier"
},
"OfferStatus": {
"@type": "OfferStatusHospitality",
"Status": "Confirmed"
}
}
},
{
"@type": "ReceiptConfirmation",
"Confirmation": {
"@type": "ConfirmationHold",
"confirmationStatus": {
"@type": "OfferStatusHospitality",
"Status": "Confirmed"
},
"Locator": {
"value": "0GQ9HS",
"sourceContext": "Travelport"
},
"OfferStatus": {
"@type": "OfferStatusHospitality",
"Status": "Confirmed"
}
}
}
]
}
}
}