Stays API FAQs

This FAQ addresses common questions about the Stays TripServices API, including both the v11 multi-step workflow and the SearchComplete API (single consolidated endpoint). These questions are organized by topic to help you quickly find the information you need.

Contact your Travelport account manager to request access. You'll need to provide your PCC (Pseudo City Code) for provisioning. Your account manager will coordinate setup for both pre-production and production environments.

The API uses OAuth 2.0 authentication. You must:

• Obtain OAuth credentials (client_id and client_secret) from Travelport
• Request an access token using the client credentials grant
• Include the Bearer token in all API requests
• Include your PCC in the XAUTH_TRAVELPORT_ACCESSGROUP header Token endpoint for pre-production.

Test your credentials with a simple API call to the search endpoint. If you receive a 401 error, verify your OAuth token is valid and hasn't expired. Tokens expire after 24 hours.

Contact Travelport support or your account manager to re-enable your account. You may need to reset your password through the provided reset link.

SearchComplete is available to all Stays TripServices API customers. Use the same authentication as v11. For pre-production testing, ensure your PCC is provisioned for SearchComplete access.

Recommendation: Use SearchComplete for new implementations. It's simpler, faster, and recommended by Travelport.

Yes. SearchComplete returns the same data as the combined v11 search, availability, and rules responses. It includes property details, available rates, room types, pricing, and rate rules including cancellation policies.

Yes, but it's not recommended. Pick one workflow and use it consistently. SearchComplete is the recommended approach for all new development.

SearchComplete currently handles search, availability, and rules. For booking operations (create, retrieve, modify, cancel), use the standard booking endpoints which work with both v11 and SearchComplete results.

Large search results are paginated automatically. The response includes a pagination object with a nextIdentifier. Use the GET request to retrieve additional pages.

You can search by:

• IATA airport or city code (e.g., "SFO")
• City name and country (e.g., "San Francisco", "US")
• Geographic coordinates with radius (latitude, longitude, radius in miles)
• Specific property IDs

The current maximum is 25 miles. If you need a wider radius, contact your account manager to discuss your use case and potential enhancements.

You can search for specific properties by ID without a strict limit, but for performance, batch requests in groups of 20-25 properties. For location-based searches, the API returns available properties within the specified area.

Yes, unless you specifically want to see properties without availability. Setting this to true filters results to only show properties that have available rooms for your dates, improving relevance.

SearchComplete includes intelligent caching to improve performance. You can control caching behavior using the TVP-Cache-Control header. Use "no-cache" for real-time pricing (slower but most current), or omit the header to use cached results when available (faster).

For cached results, rates are typically fresh within the last few minutes. For real-time rates, use TVP-Cache-Control: no-cache. Always make a final price check before booking.

To create a booking, you need:

• propertyKey - From the search response
• rateKey - From the selected rate in search results
• Guest details - Name, contact information
• Payment information - Credit card or guarantee details
• Rate rules acknowledgment - Confirm cancellation policies

Use POST /book/reservations with this information.

Include multiple offers in a single booking request, where each offer corresponds to a specific room and rate. Each room must have at least one traveler associated with it.

Travelport is working on supporting record locator references in booking requests. Contact your account manager for the current status and availability timeline for this feature.

This error indicates the hotel could not confirm the booking. Common causes include:

• Property is no longer available for those dates
• Rate has expired or changed
• Room type is sold out
• Payment or guarantee information issue

Verify your booking parameters and try again with fresh search results.

Use GET /book/reservations/{confirmationId} where confirmationId is the confirmation number returned when the booking was created.

Modifications: Use PUT /book/reservations/{confirmationId} with updated details.

Cancellations: Use DELETE /book/reservations/{confirmationId}. The response will include any applicable cancellation penalties based on the rate rules.

Cancellation policies are in the rate.rateRules.cancelPolicy object in search results. This includes the cancellation deadline and any penalty amounts. Always display this information to users before booking.

What's Happening:

Your sell requests are currently structured in a way that causes them to fail for guarantee-required rates:

• The "acceptGuaranteeChangeInd" flag is not included in initial requests
• The Payment object only includes the Amount field
• The guarantee and deposit indicator fields are left unpopulated
• This means every request is treated as if you're requesting a deposit-required rate, regardless of what the availability/rules response actually returned. When the actual rate requires a guarantee instead of a deposit, the booking fails.
• We can see that you're successfully rebooking by resending with "acceptGuaranteeChangeInd" = true, but this workaround doubles your transaction volume and creates unnecessary errors.

The Solution:

The Payment object includes two boolean fields (guaranteeInd and depositInd) that must be populated based on the rate information in your availability or rules response.

Correct Implementation:

For guarantee-required rates:

[
 {
  "Amount": {
   "code": "EUR",
   "value": 120
  },
  "guaranteeInd": true,
  "depositInd": false
 }
]

For deposit-required rates:

[
 {
  "Amount": {
   "code": "EUR",
   "value": 120
  },
  "guaranteeInd": false,
  "depositInd": true
 }
]

The rate breakdown includes:

• base - Base room rate
• totalTaxes - All applicable taxes
• totalFees - Hotel fees (resort fees, service charges, etc.)
• total - Complete amount customer pays (base + taxes + fees)

Yes. Set returnCompleteNightlyRateBreakdown: true in your search request. This returns per-night pricing in the nightlyRates array.

Zero-dollar rates occasionally appear due to promotional rates or backend data issues. These should typically be filtered out or confirmed with Travelport before displaying to users.

Use the propertyFilter.categories array in your request. Example: ["CORPORATE", "GOVERNMENT"]. This filters results to only show rates matching those categories.

• Deposit: Payment required in advance, typically non-refundable or with restricted refund policies.
• Guarantee: Hold on credit card or payment method, charged later (usually at check-in or checkout). May be fully refundable if cancelled before deadline.

Check rateRules.depositPolicy and rateRules.guaranteePolicy for specific requirements.

Booking windows vary by hotel and rate. If you receive "Travelport rates are unavailable for the property," you may be searching too far in advance. Most hotels support bookings up to 11-12 months ahead.

Contact your Travelport representative to request an export of all amenity codes. This includes standard codes (pool, gym, WiFi, etc.) that you can map to icons in your UI.

Travelport provides access to approximately 140,000 properties worldwide, with about 100,000 shared with major OTAs. Content includes aggregated inventory from multiple sources including Booking.com.

Yes. Set propertyFilter.returnAllImageURLs: true and propertyFilter.imageSize to "LARGE" (or "SMALL", "MEDIUM") to control image quality. Property descriptions, amenities, and images are included in the search response.

Detailed amenity information depends on what the property provides. Standard amenities are included, but specific policies may require accessing the property details or contacting the hotel directly.

Properties with availability "Other" may have limited availability or conditional booking rules. If this differs from "Open" status in your testing, discuss with Travelport whether these properties should be treated differently in your UI.

For optimal performance, make 3-5 concurrent requests. Travelport is expanding cache support and load handling capabilities. Contact your account manager if you need higher concurrency limits.

For 50+ properties:

• Batch requests into groups of 20-25 properties
• Make concurrent requests (3-5 at a time)
• Use caching where appropriate
• Consider using location-based search instead of property IDs if applicable

Yes, for browsing experiences. Cache results for a few minutes to improve performance. Always make a fresh no-cache request before final booking to ensure current pricing.

• Use SearchComplete instead of v11 (1 call vs 3 calls)
• Leverage caching - omit TVP-Cache-Control for faster responses
• Batch property searches appropriately (20-25 per request)
• Use concurrent requests within recommended limits (3-5)
• Request only needed data - use excludeResponseFields to reduce payload size

Check the following:

• OAuth token is valid and hasn't expired (tokens expire after 24 hours)
• Authorization header includes "Bearer" prefix
• XAUTH_TRAVELPORT_ACCESSGROUP header contains correct PCC
• Request fresh token if current one expired

This typically means:

• Property has no availability for the requested dates
• You're searching outside the property's bookable window
• Property information has changed - use fresh search results
• Cache expiration - make request with TVP-Cache-Control: no-cache

Check the errors array in the response. It includes:

• code - Error code identifying the issue
• message - Human-readable error description
• field - Specific field causing the error (if applicable)

Use this information to identify and fix the issue in your request.

There are known discrepancies between Postman examples and Swagger documentation (e.g., "Prefix" vs "Title" in PersonName). Always rely on the Swagger/OpenAPI documentation for the authoritative field mappings.

Travelport's OAuth tokens may not conform to standard JWT format. They can contain only two periods instead of the standard three. Handle these tokens as opaque strings rather than parsing them as standard JWTs.

Common causes:

• Different endpoint URLs - verify you're using correct pre-prod URLs
• PCC provisioning differences - ensure PCC is set up in pre-prod
• Feature availability - some features may not be in pre-prod yet
• Contact your account manager to align pre-prod and prod configurations

The warnings array appears at the top level of the response. It contains non-fatal issues like:

• Properties that didn't respond in time
• Partial results due to supplier timeout
• Deprecated field usage
• Rate limitations or restrictions

Always check warnings to understand if results are complete.

• OpenAPI/Swagger documentation - Available through developer portal
• Postman collections - Contact your account manager for latest version
• Code examples - Available in documentation
• Migration guides - Available for uAPI, GWS, and v11 to SearchComplete

• Account Manager - For provisioning, access, and business questions
• Travelport Support - For technical issues and troubleshooting
• Developer Portal - For documentation and API specifications
• Integration Team - For implementation guidance and best practices

For urgent issues or production outages, contact Travelport support immediately with your PCC, error details, and request/response examples.

We value your feedback on this documentation. If you have suggestions for improvements, find errors, or need clarification on any topic, please contact:

• Your Travelport Account Manager
• Travelport Support team
• Developer Portal feedback form

For urgent API issues or production support, contact Travelport support immediately.

Provide feedback about this documentation

This link does not provide Help Desk support. If you need immediate assistance with Travelport APIs, please create a support request in My Travelport or use your normal support path.