Dynamic price calendar

A price calendar shows guests the cheapest available offer for every arrival date in a window, so they can pick their dates based on price. One Best Price call powers the whole grid.

Prerequisites

Before building a calendar, make sure you have:

A working Best Price call. If not, follow the Quick start first.
A hotel ID and a group ID for the property you display.
A target date window (typically 30 to 90 days).

How it works

The Calendar endpoint returns one entry per arrival date in your requested range. Each entry contains the cheapest offer for that day. You map the response array directly onto your calendar cells: one date, one price, one availability indicator. A single call covers the whole window. No iteration, no per-day requests.

Build the calendar

The examples below assume the OAuth signing setup from the Quick start.

Request the date range you display

Call Best Price once with the first and last dates your UI shows. The default behaviour of LowestLengthOfStay fits a browse experience: it returns the best price compatible with the shortest stay, instead of pushing the user toward longer mandatory stays.

curl --request POST \
  --url https://{apiBaseUrl}/Planning/2018A/BestPrice/Calendar \
  --header 'Authorization: OAuth ...' \
  --header 'Content-Type: application/json' \
  --data '{
    "beginDate": "2026-12-07",
    "endDate": "2027-01-05",
    "guests": [{"adults": 2}],
    "filter": {
      "ratePlan": {"hotelId": <hotelId>, "groupId": <groupId>},
      "currency": "EUR"
    }
  }'

const url = "https://{apiBaseUrl}/Planning/2018A/BestPrice/Calendar";

const response = await fetch(url, {
  method: "POST",
  headers: { ...authHeaders, "Content-Type": "application/json" },
  body: JSON.stringify({
    beginDate: "2026-12-07",
    endDate: "2027-01-05",
    guests: [{ adults: 2 }],
    filter: {
      ratePlan: { hotelId: <hotelId>, groupId: <groupId> },
      currency: "EUR",
    },
  }),
});
const data = await response.json();

response = session.post(
    "https://{apiBaseUrl}/Planning/2018A/BestPrice/Calendar",
    json={
        "beginDate": "2026-12-07",
        "endDate": "2027-01-05",
        "guests": [{"adults": 2}],
        "filter": {
            "ratePlan": {"hotelId": <hotelId>, "groupId": <groupId>},
            "currency": "EUR",
        },
    },
)
data = response.json()

$response = $client->post('Planning/2018A/BestPrice/Calendar', [
    'json' => [
        'beginDate' => '2026-12-07',
        'endDate'   => '2027-01-05',
        'guests'    => [['adults' => 2]],
        'filter'    => [
            'ratePlan' => ['hotelId' => <hotelId>, 'groupId' => <groupId>],
            'currency' => 'EUR',
        ],
    ],
]);
$data = json_decode($response->getBody(), true);

var request = new RestRequest("/BestPrice/Calendar", Method.Post);
request.AddJsonBody(new
{
    beginDate = "2026-12-07",
    endDate = "2027-01-05",
    guests = new[] { new { adults = 2 } },
    filter = new
    {
        ratePlan = new { hotelId = <hotelId>, groupId = <groupId> },
        currency = "EUR"
    }
});

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

String body = mapper.writeValueAsString(Map.of(
    "beginDate", "2026-12-07",
    "endDate", "2027-01-05",
    "guests", List.of(Map.of("adults", 2)),
    "filter", Map.of(
        "ratePlan", Map.of("hotelId", <hotelId>, "groupId", <groupId>),
        "currency", "EUR"
    )
));

HttpPost request = new HttpPost("https://{apiBaseUrl}/Planning/2018A/BestPrice/Calendar");
request.setEntity(new StringEntity(body, "UTF-8"));
request.setHeader("Content-Type", "application/json");
consumer.sign(request);

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

Render available dates with their price

For each entry where status is Available, display totalPrice with currency. The arrivalDate field tells you which calendar cell the entry belongs to.

data.forEach(day => {
  if (day.status === "Available") {
    renderCell(day.arrivalDate, {
      price: day.totalPrice,
      currency: day.currency,
    });
  }
});

for day in data:
    if day["status"] == "Available":
        render_cell(day["arrivalDate"], {
            "price": day["totalPrice"],
            "currency": day["currency"],
        })

foreach ($data as $day) {
    if ($day['status'] === 'Available') {
        renderCell($day['arrivalDate'], [
            'price'    => $day['totalPrice'],
            'currency' => $day['currency'],
        ]);
    }
}

foreach (var day in data.EnumerateArray())
{
    if (day.GetProperty("status").GetString() == "Available")
    {
        RenderCell(day.GetProperty("arrivalDate").GetString()!, new
        {
            price = day.GetProperty("totalPrice").GetDecimal(),
            currency = day.GetProperty("currency").GetString()
        });
    }
}

for (JsonNode day : data) {
    if ("Available".equals(day.get("status").asText())) {
        renderCell(
            day.get("arrivalDate").asText(),
            Map.of(
                "price", day.get("totalPrice").decimalValue(),
                "currency", day.get("currency").asText()
            )
        );
    }
}

Surface promotions when the API returns them

When originalTotalPrice is present, the day has an active promotion. In a tight calendar grid, show only totalPrice and signal the promotion with a visual cue: a coloured cell, a small badge, or a corner icon.

if (day.originalTotalPrice) {
  markCellAsPromo(day.arrivalDate);
}

if day.get("originalTotalPrice"):
    mark_cell_as_promo(day["arrivalDate"])

if (!empty($day['originalTotalPrice'])) {
    markCellAsPromo($day['arrivalDate']);
}

if (day.TryGetProperty("originalTotalPrice", out _))
{
    MarkCellAsPromo(day.GetProperty("arrivalDate").GetString()!);
}

if (day.has("originalTotalPrice") && !day.get("originalTotalPrice").isNull()) {
    markCellAsPromo(day.get("arrivalDate").asText());
}

Disable unavailable dates with the right reason

For every entry where status is NotAvailable, grey out the cell; show an OnRequest day as bookable with a distinct cue, since the hotel confirms it before booking. The unavailabilityReason tells you why, which lets you display a more helpful tooltip than a generic “unavailable”.

Reason	Tooltip suggestion
`GuestsDoNotFitInRoom`	Too many guests for the rooms available that day.
`NoArrival`	No arrival possible on this date.
`MinimumStayTooLong`	Available, but requires a longer stay.
`Other`	Sold out.

Tips

Mind the minimum stay. The totalPrice is already a per-night average, so calendar cells are visually comparable without any computation on your side. What changes when minimumStay is greater than 1 is the booking constraint: the visitor must commit to that many nights to pay that rate. Two strategies, depending on your hotel type:
- City or business hotels: force a single-night view by setting filter.maximumStay: 1. The API only returns days bookable as 1-night stays, so visitors never face a stay-length surprise at booking.
- Resorts or luxury properties: display the price as-is and surface the constraint with a small label on the cell (“min 3 nights”). Multi-night stays are the norm here, and hiding those days would empty most of the calendar.
- Seasonal mix: default to displaying as-is so you never hide bookable days, then switch to the 1-night view on date ranges where short stays are the rule.
Cache the response. Best Price data is browse-heavy and changes slowly. A short cache cuts response time on repeat views.
Watch closedOnDeparture. When true, guests cannot check out that day. It does not affect arrival, but it constrains the departure dates compatible with the arrival.

Reference

Full schema for every field returned by Best Price.

Best practices

Caching, performance, and resilience patterns.

Get started

Build

Resources

Dynamic price calendar

Prerequisites

How it works

Build the calendar

Request the date range you display

Render available dates with their price

Surface promotions when the API returns them

Disable unavailable dates with the right reason

Tips

Reference

Best practices

​Prerequisites

​How it works

​Build the calendar

Request the date range you display

Render available dates with their price

Surface promotions when the API returns them

Disable unavailable dates with the right reason

​Tips

​Related

Reference

Best practices

Prerequisites

How it works

Build the calendar

Tips

Related