Alternative availability

A guest asks for a specific stay, and the hotel has nothing to sell for it. Rather than show a dead end, offer the nearest bookable option: spread the party across rooms, extend or reduce the stay, or, when the hotel belongs to a group, search the other hotels nearby. Each option keeps the guest in the funnel and improves conversion.

The examples reuse the OAuth 1.0 signing from the Quick start. Replace {sessionId} with your session.

Move the guests across rooms

When the party does not fit in a single room, the room search can split it across rooms (for example 4 adults as 2 + 2). Add AlternativeGuests to X-AVP-Properties on GET /v2/{sessionId}/search/rooms:

curl --request GET \
  --url 'https://{apiBaseUrl}/v2/{sessionId}/search/rooms' \
  --header 'Authorization: OAuth ...' \
  --header 'X-AVP-Properties: AlternativeGuests'

const url = "https://{apiBaseUrl}/v2/{sessionId}/search/rooms";

const response = await fetch(url, {
  method: "GET",
  headers: {
    ...oauth.toHeader(oauth.authorize({ url, method: "GET" }, token)),
    "X-AVP-Properties": "AlternativeGuests",
  },
});

const results = await response.json();

response = session.get(
    "https://{apiBaseUrl}/v2/{sessionId}/search/rooms",
    headers={"X-AVP-Properties": "AlternativeGuests"},
)

results = response.json()

$response = $client->get('v2/{sessionId}/search/rooms', [
    'headers' => ['X-AVP-Properties' => 'AlternativeGuests'],
]);

$results = json_decode($response->getBody(), true);

var request = new RestRequest("/v2/{sessionId}/search/rooms", Method.Get);
request.AddHeader("X-AVP-Properties", "AlternativeGuests");

var response = await client.ExecuteAsync(request);
var results = JsonDocument.Parse(response.Content!).RootElement;

HttpGet request = new HttpGet("https://{apiBaseUrl}/v2/{sessionId}/search/rooms");
request.setHeader("X-AVP-Properties", "AlternativeGuests");
consumer.sign(request);

JsonNode results;
try (CloseableHttpResponse response = client.execute(request)) {
    results = mapper.readTree(EntityUtils.toString(response.getEntity()));
}

The result is flagged AvailabilityWithAlternativeGuests, with one allocation entry per room. Only one split is returned:

{
  "unavailabilityType": "AvailabilityWithAlternativeGuests",
  "alternativeGuestsAllocation": [
    { "adults": 2, "children": 0, "infants": 0, "position": 1, "memberLevel": 0 },
    { "adults": 2, "children": 0, "infants": 0, "position": 2, "memberLevel": 0 }
  ]
}

Extend or reduce the stay

When a rate is blocked by a minimum or maximum stay, the room search can return it at a length that works. Add FetchExtendedStay (minimum-stay) or FetchReducedStay (maximum-stay) to X-AVP-Properties:

curl --request GET \
  --url 'https://{apiBaseUrl}/v2/{sessionId}/search/rooms' \
  --header 'Authorization: OAuth ...' \
  --header 'X-AVP-Properties: FetchExtendedStay|FetchReducedStay'

const url = "https://{apiBaseUrl}/v2/{sessionId}/search/rooms";

const response = await fetch(url, {
  method: "GET",
  headers: {
    ...oauth.toHeader(oauth.authorize({ url, method: "GET" }, token)),
    "X-AVP-Properties": "FetchExtendedStay|FetchReducedStay",
  },
});

const results = await response.json();

response = session.get(
    "https://{apiBaseUrl}/v2/{sessionId}/search/rooms",
    headers={"X-AVP-Properties": "FetchExtendedStay|FetchReducedStay"},
)

results = response.json()

$response = $client->get('v2/{sessionId}/search/rooms', [
    'headers' => ['X-AVP-Properties' => 'FetchExtendedStay|FetchReducedStay'],
]);

$results = json_decode($response->getBody(), true);

var request = new RestRequest("/v2/{sessionId}/search/rooms", Method.Get);
request.AddHeader("X-AVP-Properties", "FetchExtendedStay|FetchReducedStay");

var response = await client.ExecuteAsync(request);
var results = JsonDocument.Parse(response.Content!).RootElement;

HttpGet request = new HttpGet("https://{apiBaseUrl}/v2/{sessionId}/search/rooms");
request.setHeader("X-AVP-Properties", "FetchExtendedStay|FetchReducedStay");
consumer.sign(request);

JsonNode results;
try (CloseableHttpResponse response = client.execute(request)) {
    results = mapper.readTree(EntityUtils.toString(response.getEntity()));
}

The candidate comes back with the adjusted availabilityType on the room, and an availabilityInfo on the rate giving the required nights:

{
  "rooms": [
    {
      "availabilityType": "ExtendedStay",
      "rates": [
        { "availabilityInfo": { "reason": "MinStay", "minStay": 3, "maxStay": 0 } }
      ]
    }
  ]
}

FetchReducedStay mirrors this with availabilityType: "ReducedStay" and reason: "MaxStay". On a rate blocked by a minimum stay, FetchExtendedStay takes precedence over AlternativeGuests.

Search the group’s other hotels

This path applies when the hotel belongs to a group (a multi-hotel booking engine). It picks up where the chosen hotel ran out, in two steps.

The chosen hotel is full. The room search at the selected hotel returns no availability.
Open the search to the group. Set selectedHotelId to null in the session context, centre a Localisation filter on the hotel’s area, then search the hotels nearby.

Set the filter with PATCH /v2/{sessionId}/session/filters/hotels, passing the latitude, longitude, and a radius in metres:

{
  "filters": [
    { "type": "Localisation", "values": ["48.8713379", "2.3441099", "5000"] }
  ]
}

Then search the group for the available hotels nearby:

curl --request GET \
  --url 'https://{apiBaseUrl}/v2/{sessionId}/search/hotels' \
  --header 'Authorization: OAuth ...' \
  --header 'X-AVP-Properties: Description'

const url = "https://{apiBaseUrl}/v2/{sessionId}/search/hotels";

const response = await fetch(url, {
  method: "GET",
  headers: {
    ...oauth.toHeader(oauth.authorize({ url, method: "GET" }, token)),
    "X-AVP-Properties": "Description",
  },
});

const hotels = await response.json();

response = session.get(
    "https://{apiBaseUrl}/v2/{sessionId}/search/hotels",
    headers={"X-AVP-Properties": "Description"},
)

hotels = response.json()

$response = $client->get('v2/{sessionId}/search/hotels', [
    'headers' => ['X-AVP-Properties' => 'Description'],
]);

$hotels = json_decode($response->getBody(), true);

var request = new RestRequest("/v2/{sessionId}/search/hotels", Method.Get);
request.AddHeader("X-AVP-Properties", "Description");

var response = await client.ExecuteAsync(request);
var hotels = JsonDocument.Parse(response.Content!).RootElement;

HttpGet request = new HttpGet("https://{apiBaseUrl}/v2/{sessionId}/search/hotels");
request.setHeader("X-AVP-Properties", "Description");
consumer.sign(request);

JsonNode hotels;
try (CloseableHttpResponse response = client.execute(request)) {
    hotels = mapper.readTree(EntityUtils.toString(response.getEntity()));
}

Each hotel comes back with a location.distance: order the results by that value in your interface to lead with the closest one.

Tips

Ask for alternatives explicitly. The room search returns them only when you set the values on X-AVP-Properties, and you can combine several in one call.
Know why it failed. Add DetailedUnavailabilityType to see whether the block is on the room, the rate, both, or the guests, then pick the matching alternative.
Start at the same hotel. A room split or a shifted stay is a smaller change than a new hotel, so it converts better. Keep the nearby hotel as a fallback.

Search rooms

Room search, alternative occupancies, and availability hints.

Filter hotels

Set the Localisation, Budget, Rating, and Amenities filters.

Get started

Build

Resources

Alternative availability

Move the guests across rooms

Extend or reduce the stay

Search the group’s other hotels

Tips

Search rooms

Filter hotels

​Move the guests across rooms

​Extend or reduce the stay

​Search the group’s other hotels

​Tips

​Related

Search rooms

Filter hotels

Move the guests across rooms

Extend or reduce the stay

Search the group’s other hotels

Tips

Related