Marriott Bonvoy Price Calendar API
See the lowest available rate for every check-in date at one Marriott property, in a single request.
Overview
One price per check-in date
For each date from date_from to date_to (inclusive), this returns the lowest rate for a stay of nights nights starting that date. Dates with no bookable rate are returned with available set to false and null prices.
Take the property_id from a Search result (for example LAXJW) and request a window of up to 36 check-in dates. Pass a corporate_code to price only rates under that code, or set use_points=true for a Bonvoy points calendar.
Endpoint URL
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| property_id | string | Required | Marriott property code from the Search endpoint (e.g., "LAXJW", "NYCXR") |
| date_from | date | Required | First check-in date (YYYY-MM-DD). Today or later. |
| date_to | date | Required | Last check-in date (YYYY-MM-DD), inclusive. On or after date_from and at most 35 days after it (up to 36 dates). |
| nights | integer | Optional | Length of stay priced for each check-in date (1-9). Default: 1 |
| adults | integer | Optional | Adults per room (1-10). Default: 2 |
| rooms | integer | Optional | Number of rooms (1-8). Default: 1 |
| corporate_code | string | Optional | Corporate or promotional rate code, 1-16 letters or digits (e.g., MMP). When set, only rates under that code are returned: every available date is priced at a rate under the code. |
| use_points | boolean | Optional | Return a Bonvoy points (award) calendar instead of cash. Cannot be combined with corporate_code. Default: false |
Window limit
date_to must be at most 35 days after date_from, otherwise the API returns 400 RANGE_TOO_LARGE. Cover longer periods with consecutive windows.
Response Format
Response Structure
- success: Boolean indicating request success
- property_id, date_from, date_to, nights: Echo of the request
- corporate_code: The code you sent, or null
- use_points: Whether this is a points calendar
- currency: The property's currency (first non-null date currency), or null when no date is available
- available_count: Number of dates with
available: true - dates: One entry for every date from
date_fromtodate_to, in order
Date Fields
| Field | Type | Description |
|---|---|---|
| date | string | Check-in date (YYYY-MM-DD) |
| check_out | string | Check-out date: date plus nights |
| available | boolean | False when Marriott offers no bookable rate for that check-in date and stay length (with corporate_code: no rate under that code; with use_points: no award availability). All price fields are null then. |
| per_night | float | null | Lowest average nightly cash rate for the stay, before taxes and fees |
| stay_total | float | null | Cash total for the stay before taxes and fees (per_night × nights, as Marriott reports it) |
| currency | string | null | The property's own currency as Marriott reports it (e.g., GBP for a London hotel). Prices are not converted. |
| points_total | integer | null | Bonvoy points for the whole stay. Only set with use_points=true, where the cash fields are null. |
Corporate codes
Marriott does not reject a code it does not recognise. A valid request with an unknown code returns 200 with every date available=false. The calendar carries no rate plan code: with corporate_code set, every available date is priced at a rate under that code, which is your signal that the code applied.
Recipe: Flexible Dates
To find the cheapest dates across several Marriott hotels in an area, combine Search with this endpoint. There is no separate flexible-dates endpoint.
- Call Search for the area with one representative stay and collect each hotel's
property_id. If you negotiate a corporate rate, pass yourcorporate_codewithcorporate_only=trueto keep only hotels that offer it. - For each
property_id, call this endpoint with your date window,nights, and the samecorporate_code. - Keep the entries with
available: trueand pick the loweststay_total. Compare totals only within one currency, since each property reports its own. - Confirm the chosen dates with Rooms to get room types, rate plans, and cancellation terms.
Each call costs one credit, so a search plus calendars for ten hotels costs eleven credits.
Error Responses
Errors follow the RFC 7807 Problem Details format with provider: "marriott" and product: "bonvoy".
400 Bad Request
INVALID_DATE_FORMAT: a date is not YYYY-MM-DDINVALID_DATES:date_tois beforedate_fromPAST_DATES:date_fromis in the pastRANGE_TOO_LARGE:date_tois more than 35 days afterdate_fromINVALID_PARAMETERS:corporate_codeanduse_pointswere sent together
{
"type": "https://api.stayapi.com/errors/range-too-large",
"title": "Range Too Large",
"status": 400,
"detail": "date_to must be within 35 days of date_from",
"provider": "marriott",
"product": "bonvoy",
"error_code": "RANGE_TOO_LARGE"
}
404 Not Found
PROPERTY_NOT_FOUND: no Marriott property matches the property_id.
502 / 503
Marriott returned an error or could not be reached (502 UPSTREAM_ERROR), or the service is temporarily at capacity (503 SERVICE_OVERLOADED). For a 503, wait for the Retry-After header before trying again.
Related Endpoints
Marriott Bonvoy Search
Find Marriott hotels near a coordinate and get their property codes
View Documentation →Marriott Bonvoy Rooms
Get room types, rate plans, and cancellation terms for the dates you pick
View Documentation →