Deals API Frequently Asked Questions

This article answers the most common questions about the Xeni Deals API, from how deals are sourced to how to complete a booking.

How often are deals updated?

Deals are sourced in real time from multiple hotel suppliers. Each time you call the endpoint, the API queries current supplier inventory and returns the latest available deals. This means the set of deals you receive can change from one request to the next as suppliers add, modify, or remove promotions.

In practice, deals for a given location tend to be relatively stable over short periods (minutes), but can shift significantly over the course of hours as supplier pricing and availability change. We recommend refreshing deal data every 5 to 10 minutes if you are displaying deals on a long-lived page.

Can I filter deals by hotel star rating?

The Deals API does not currently support server-side filtering by star rating. The endpoint returns all available deals near the specified location.

However, the response includes star rating information for each property, so you can filter on the client side:

// Filter for 4-star and above
const premiumDeals = deals.filter(deal => deal.star_rating >= 4);

This approach gives you full control over the filtering logic and allows you to offer users interactive filter controls without additional API calls.

How do I book a deal?

The Deals API is a discovery endpoint — it surfaces available deals but does not handle bookings directly. To book a hotel from a deal, use the Xeni Hotels API:

1. Capture the property ID from the deal the user selects.
2. Check availability by calling the Hotels API availability endpoint with the property ID, desired dates, and guest count.
3. Confirm pricing using the Hotels API price confirmation endpoint to lock in the rate.
4. Create the booking through the Hotels API booking endpoint.

For more details, see the Hotels API documentation.

What is the difference between deals and a regular hotel search?

Can I get deals for a future date?

The Deals API does not accept check-in or check-out date parameters. It returns currently available promotional offers for properties near the specified location. These deals may include travel windows (date ranges during which the deal is valid), but you cannot query for deals on a specific future date.

If you need to find hotel availability and pricing for specific dates, use the Hotels API search and availability endpoints instead.

What does the top_destination parameter do?

When top_destination is set to true, the API adjusts its behavior to return deals for popular, well-known travel destinations near the provided coordinates rather than strictly the closest hotels.

For example, if you pass coordinates for a suburban area outside Miami with topdestination=false (or omit the parameter), you might get deals for nearby suburban hotels. With topdestination=true, the API may return deals for popular Miami Beach hotels or other well-known destinations in the region.

This is useful for:

• "Trending Destinations" sections — Highlight popular locations with active deals.
• Inspiration-focused UIs — Show aspirational destinations to encourage browsing.
• Fallback displays — When a proximity search returns few results, a top-destination query can fill the page with appealing options.

# Proximity-based (default behavior)
GET /hotels/api/v2/deals?lat=25.95&long=-80.15&currency=USD

Top destinations near this area
GET /hotels/api/v2/deals?lat=25.95&long=-80.15&currency=USD&top_destination=true

What currencies are supported?

The API supports most ISO 4217 currency codes including USD, EUR, GBP, CAD, AUD, MXN, JPY, BRL, INR, and many more. See Supported Currencies and Localization for the full list and details on how currency conversion works.

What happens if there are no deals for my location?

If no deals are currently available near the provided coordinates, the API returns a successful response with an empty deals array. This is not an error.

To handle this gracefully:

• Display a friendly message like "No deals available nearby right now."
• Offer to show deals for a different location.
• Fall back to a top_destination=true request to show popular deals in the broader region.
• Encourage the user to check back later, as deals are updated frequently.

How large is the search radius?

The API determines the search radius automatically based on the density of available deals near the provided coordinates. In areas with many hotel properties (such as major cities), the radius may be tighter. In less dense areas, the radius may expand to ensure useful results are returned.

You do not need to specify a radius — the API optimizes this for you.

Do I need authentication to use the Deals API?

Yes. Like all Xeni APIs, the Deals API requires valid API credentials. You will need your API key and secret, which are provided during onboarding. Requests without valid authentication will receive a 401 Unauthorized response.

See the Authentication documentation for details on generating authentication signatures.

Can I use the Deals API for non-hotel deals?

No. The Deals API is specifically for hotel deals. It does not return deals for flights, car rentals, activities, or other travel products. For those, refer to the respective API collections in the Xeni API documentation.

Who should I contact for support?

If you have questions about the Deals API or need help with your integration, contact Xeni support at customersupport@xeni.com. When reporting an issue, include the x-correlation-id from the problematic request to help the support team investigate quickly.