Check the Hotel Release Notes for updates across all Hotel APIs.

Hotel Availability API Reference

POST

availability/catalogofferingshospitality

Use this base path if you have not yet received or not migrated to the new credentials from Travelport:

Pre-production https://api.pp.travelport.com/11/hotel/ | Production https://api.travelport.com/11/hotel/

Use this base path after you have migrated to the new credentials from Travelport (using .net instead of .com):

Pre-production https://api.pp.travelport.net/11/hotel/ | Production https://api.travelport.net/11/hotel/

Related Content: JSON Hotel APIs Guide, Hotel Search Guide, Availability Pagination API Reference

Hotel Availability returns room types and rates available at one or more specified properties on specified dates.

After Availability, you can book the hotel room/s with either the Create Reservation full payload or reference payload request (what's the difference?).


Request

As part of the request requirements, also see Authentication and Common Hotel API Headers.

Query Parameters

None.

Request Body

For additional examples, download the developer toolkits and see Using Postman and Developer Toolkits.
The red asterisk at the end of an object name below, as in Traveler*, marks that object as required in the request.

CatalogOfferingsQueryRequest*

Top level object.


CatalogOfferingsRequest*

Top level object.

Includes StayDates and HotelSearchCriterion objects.

requestedCurrency: Code for currency to display results in. If sent, the response includes a currency rate conversion value for the currency specified. This value can be applied to the hotel's local pricing.

maxResponseWaitTime: Supports a timeout in milliseconds when requesting availability for multiple properties. If sent, the request times out at the specified time and returns all properties retrieved at that point.

verboseResponseInd : Boolean to indicate whether to group common property details.

true: Disables the grouping of common property details in the response's ReferenceList object and instead returns them for each property in Offer/Products/Product.

false: Returns common details across properties in a ReferenceList object with a cross-reference for each offer. Default if not sent.


StayDates*

Check-in and -out dates.

start*: String. Check-in date in YYYY-MM-DD format.

end*: String. Check-out date in YYYY-MM-DD format.


HotelSearchCriterion*

Top level object for hotel search data.

Includes RateCandidates, PropertyRequest, and RoomStayCandidates objects.

numberOfRooms*: Number. Supports values 1-9 inclusive. Number of rooms requested at a single property.

AggregatorList : Restrict the search to a specific aggregator.

Accepted values are:

  • TVPT Travelport

  • BKNG Booking.com

User must be authorized for any aggregator selected.


RateCandidates

Rate plans, access codes, and rate categories. Send only if requesting rate plans.

Includes RateCandidate object.

prePayRatesOnlyInd: Boolean: true returns only pre-paid rates; false allows the return of all rates.

A prepay rate charges the full amount on the credit card immediately on booking.

postPayRatesOnlyInd : Boolean: true returns only post-paid rates; false allows the return of all rates.

A postpay rate (most common in the US) charges the credit card at the property when the guest checks in.

removeSpecialRatesInd : Boolean (true/false). Used to request the removal of rate category (Promotional/Package/etc.) rates that may have been returned by the supplier as typical published rates.

  • If the indicator is True + negotiated rates are requested in the request => the indicator eliminates the rest of the rate category rates but keeps the published and negotiated rates.

  • If the indicator is True + one or more specific rate categories are requested in the request =>the indicator is ignored and the rate category is applied.

  • If the indicator is True and there are no negotiated rates or rate category rates in the request => the special rates removal is applied and all rate category rates are filtered out.

  • If the indicator has the value False => no special filtering applied.

  • If the indicator is absent, the default is False => no special filtering applied.


RateCandidate

Rate plan details, if requesting. Send one instance of RateCandidate for each rate plan to request.

The values required differ according to whether you are sending a negotiated rate code or a rate category.

rateCode* for negotiated rate code: One or more negotiated rate codes. N/A for rate category

Each rateCode must be associated with a chainCode per below.

rateCategory* for rate category: Send a supported value of Multi-level/Negotiated/Secure for negotiated rate code.

For a rate category, send one or up to 8 rate categories to search for, such as Weekend or Government. If the supplier has rates available for the requested category, the response contains those rates and indicates them as such. Note that some properties do not return these rates unless explicitly requested. Categories are spelled for readability in this document. Refer to the OAS (aka Swagger) files provided by Travelport for exact spelling. Travelport translates the category of “All” into the category set of Promotional, Package, Senior Citizen, Family Plan, Weekend, Association, Corporate, Government.

rateID: ID of the rate plan associated with the negotiated rate. Optional; will be added automatically if missing.

chainCode* for rate code: Chain code for the property. Optional for rate category

propertyCode* for rate code: Code for the property within the hotel chain. Optional for rate category


PropertyRequest*

Property details for each property requested, up to 10 properties. Send a separate instance of PropertyRequest for each property.

Includes PropertyKey object.


PropertyKey*

Chain and property codes.

chainCode*: String. Chain code for the property.

propertyCode*: String. Property code for the property.


RoomStayCandidates*

Top level object for traveler information. Includes RoomStayCandidate object.


RoomStayCandidate*

Top level object. Includes GuestCounts object.


GuestCounts*

Top level object. Includes GuestCount object.


GuestCount*

Guest count and age/s.

count*: Number. Number of travelers with this ageQualifyingCode.

ageQualifyingCode : String. Required only for children or if traveler age is relevant, such as for a senior discount.

Supported values and meanings:

  • 10: Traveler in this GuestCount is an adult

  • 8: Traveler in this GuestCount is a child

age: String. Age of traveler. Required only when request includes a child in room.


CustomerLoyalty

String. One frequent guest number.

supplier: String. Two character hotel supplier code or brand code of the loyalty program for frequent guest use. For frequent flyer programs, send the two-character air supplier code of loyalty program

value: String. Number on loyalty card.

Example request body

{
  "CatalogOfferingsQueryRequest": {
    "CatalogOfferingsRequest": [
      {
        "@type": "CatalogOfferingsRequestHospitality",
        "requestedCurrency": "USD",
        "StayDates": {
          "start": "2025-12-01",
          "end": "2025-12-02"
        },
        "HotelSearchCriterion": {
          "@type": "HotelSearchCriterion",
          "AggregatorList": [
            "TVPT"
          ],
          "PropertyRequest": [
            {
              "@type": "PropertyRequest",
              "PropertyKey": {
                "@type": "PropertyKey",
                "propertyCode": "35910",
                "chainCode": "TX"
              }
            }
          ],
          "RoomStayCandidates": {
            "@type": "RoomStayCandidates",
            "RoomStayCandidate": [
              {
                "@type": "RoomStayCandidate",
                "GuestCounts": {
                  "@type": "GuestCounts",
                  "GuestCount": [
                    {
                      "@type": "GuestCount",
                      "count": "1"
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    ]
  }
}

 


Response

By default, common information from each room offer is consolidated into the single object ReferenceList. If the optional verboseResponseInd indicator is sent in the request, ReferenceList is not returned and common property details are not grouped. See the description for the Product object. Note that the objects in the table below display in a different order depending on whether information is grouped in ReferenceList or returned in each Product object.
For additional examples, download the developer toolkits and see Using Postman and Developer Toolkits.

The following example response has been edited for readability to return only one instance of CatalogOffering. Many more would typically be returned. This example follows the default behavior of consolidating hotel details such as address and telephone in the ReferenceList object. You can disable the return of ReferenceList by sending verboseResponseInd=true in the request.

The top level objects in the Availability response are listed below. For details see the individual sections following.

CatalogOfferingsHospitalityResponse

Top level object for response. Properties:

transactionId: System-generated unique ID for this response. Can be used for internal tracking and troubleshooting

Includes CatalogOfferings and CurrencyRateConversion objects. Includes ReferenceList object unless verboseResponseInd was set to true to disable consolidating common property information.


CatalogOfferings

Top level object that groups all offers in the response. In the hotel APIs an offer is a unique rate for one bookable room at specified terms and conditions. Properties:

totalCatalogOffering: Total number of rates available for this request.

catalogOfferingPerPage: Total number of rates returned per page.

numberOfPages: Total number of pages created by this request.

Includes CatalogOffering object.


CatalogOffering

Array. Each instance returns information related to one bookable room. Properties:

id: Unique offer identifier that can be sent in subsequent Rules and Create Reservation reference payload requests to reference this offer.

Offers cached from the Availability response are stored for 30 minutes. If a rules request or reservation is not created within 30 minutes, a new Availability request must be sent.

Includes the Identifier, ProductOptions, Price, and TermsAndConditions objects.

Each instance of CatalogOffering object returns a unique rate. A response returns a maximum of 100 rates. The first rate in the list is the single lowest rate returned no matter how many aggregators respond. The remaining rates are grouped in the order of rates returned from Travelport, followed by rates returned from Booking.com.

Identifier

Defines which supplier system returned that specific room rate (offer). Properties:

authority: Indicates which supplier returned the offer. Possible values are:

  • TVPT: Travelport
  • BKNG: Booking.com

value: Unique offer identifier that can be sent in subsequent Rules and Create Reservation reference payload requests to reference this offer.

Booking.com access requires additional provisioning and a direct agreement with the supplier. Contact your Travelport account manager for details.






Example with ReferenceList

{
 "CatalogOfferingsHospitalityResponse": {
  "@type": "CatalogOfferingsHospitalityResponse",
  "CatalogOfferings": {
   "@type": "CatalogOfferings",
   "totalCatalogOffering": 55,
   "catalogOfferingPerPage": 55,
   "numberOfPages": 1,
   "CatalogOffering": [
    {
     "@type": "CatalogOfferingHospitality",
     "id": "108c5875-c822-4d2e-bb9f-c96368100f4a:a709ffcdc1f681c5cf3f1d7da1a8ebfc",
     "Identifier": {
      "value": "108c5875-c822-4d2e-bb9f-c96368100f4a:a709ffcdc1f681c5cf3f1d7da1a8ebfc",
      "authority": "TVPT"
     },
     "ProductOptions": [
      {
       "@type": "ProductOptions",
       "Product": [
        {
         "@type": "ProductHospitalityOffer",
         "propertyDatesRef": "48f9f29a-6520-42e4-ac82-9b79b814b294",
         "bookingCode": "H00SM3H",
         "RoomType": {
          "@type": "RoomType",
          "RoomCharacteristics": {
           "@type": "RoomCharacteristics",
           "typeCode": "75",
           "smokingAllowed": "No",
           "BedConfiguration": [
            {
             "quantity": 1,
             "bedType": "King Bed(s)",
             "size": "180 cm X 200 cm"
            }
           ],
           "accessibleRoom": "No"
          },
          "Description": {
           "value": "Non-Refundable, Classic, Guest Room, 1 King"
          }
         }
        }
       ]
      }
     ],
     "Price": {
      "@type": "PriceDetail",
      "CurrencyCode": {
       "value": "USD"
      },
      "Base": 159.2,
      "TotalTaxes": 25.07,
      "TotalPrice": 184.27,
      "PriceBreakdown": [
       {
        "@type": "PriceBreakdownHospitality",
        "roomPricingType": "Per night",
        "NightlyRate": [
         {
          "@type": "NightlyRate",
          "startDate": "2025-12-01",
          "nights": 1,
          "Amount": {
           "@type": "Amount",
           "CurrencyCode": {
            "value": "USD"
           },
           "Base": 159.2,
           "Taxes": {
            "@type": "TaxesDetail",
            "TotalTaxes": 25.07,
            "Tax": [
             {
              "value": 25.07,
              "currencyCode": "USD",
              "taxCode": "8",
              "purpose": "Lodging tax",
              "description": "Lodging tax",
              "includedInBase": "No"
             }
            ]
           },
           "Total": 184.27
          }
         }
        ],
        "AverageNightlyRate": [
         {
          "value": 159.2,
          "code": "USD",
          "approximateInd": true
         }
        ]
       },
       {
        "@type": "PriceBreakdownHospitality",
        "Amount": {
         "@type": "Amount",
         "CurrencyCode": {
          "value": "USD"
         },
         "Base": 159.2,
         "Taxes": {
          "@type": "TaxesDetail",
          "TotalTaxes": 25.07,
          "Tax": [
           {
            "value": 25.07,
            "currencyCode": "USD",
            "taxCode": "8",
            "purpose": "Lodging tax",
            "description": "Lodging tax",
            "includedInBase": "No"
           }
          ]
         },
         "Total": 184.27
        },
        "Commission": {
         "@type": "Commission",
         "application": "Commissionable"
        },
        "roomPricingType": "Per stay",
        "Description": "Prepay Non-Refundable, Prepay In Full, "
       }
      ]
     },
     "TermsAndConditions": {
      "@type": "TermsAndConditionsHospitality",
      "Guarantee": [
       {
        "@type": "Guarantee",
        "guaranteeType": "DepositRequired"
       }
      ],
      "CancelPenalty": [
       {
        "@type": "CancelPenalty",
        "Description": "If you cancel, modify, or do not arrive until Dec 01, 2025, you will be charged with a fee of 100% of the total stay.",
        "Deadline": {
         "@type": "Deadline",
         "SpecificDate": {
          "start": "2025-10-01"
         }
        },
        "HotelPenalty": {
         "@type": "HotelPenaltyPercent",
         "appliesTo": "Amount",
         "Percent": 100
        },
        "Refundable": "No"
       }
      ],
      "Description": [
       "Prepay Non-Refundable, Prepay In Full, ",
       "Non-Refundable, Classic, Guest Room, 1 King"
      ],
      "RatePaymentInfo": "PrePay"
     }
    }
   ]
  },
  "transactionId": "caceae2b-8779-4241-997b-8155f770dbf5",
  "traceId": "02c72e12-e05e-4423-8097-9465cfff3a24",
  "Result": {
   "@type": "Result",
   "Warning": [
    {
     "@type": "Warning",
     "StatusCode": 404,
     "Message": "Rates returned without cancel policy require a rule request for complete information",
     "NameValuePair": [
      {
       "value": "TX",
       "name": "ChainCode"
      },
      {
       "value": "35910",
       "name": "PropertyCode"
      }
     ]
    }
   ]
  },
  "ReferenceList": [
   {
    "@type": "ReferenceListPropertyDates",
    "PropertyDates": [
     {
      "@type": "PropertyDates",
      "adaCompliant": "No",
      "id": "48f9f29a-6520-42e4-ac82-9b79b814b294",
      "propertyName": "Magnolia Hotel Denver a Tribute Portfolio Hotel",
      "PropertyAddress": {
       "@type": "Address",
       "AddressLine": [
        "818 17th Street"
       ],
       "City": "Denver",
       "StateProv": {
        "name": "CO"
       },
       "Country": {
        "name": "US"
       },
       "PostalCode": "80202"
      },
      "PropertyKey": {
       "@type": "PropertyKey",
       "chainCode": "TX",
       "propertyCode": "35910"
      },
      "DateRange": {
       "start": "2025-12-01",
       "end": "2025-12-02"
      },
      "GeoLocation": {
       "latitude": 39.746847,
       "longitude": -104.992447
      },
      "Telephone": {
       "phoneNumber": "607-9000",
       "cityCode": "BJC"
      }
     }
    ]
   }
  ]
 }
}