Browse documentation
GET

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

GET https://api.stayapi.com/v1/marriott/bonvoy/price-calendar

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_from to date_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.

  1. Call Search for the area with one representative stay and collect each hotel's property_id. If you negotiate a corporate rate, pass your corporate_code with corporate_only=true to keep only hotels that offer it.
  2. For each property_id, call this endpoint with your date window, nights, and the same corporate_code.
  3. Keep the entries with available: true and pick the lowest stay_total. Compare totals only within one currency, since each property reports its own.
  4. 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-DD
  • INVALID_DATES: date_to is before date_from
  • PAST_DATES: date_from is in the past
  • RANGE_TOO_LARGE: date_to is more than 35 days after date_from
  • INVALID_PARAMETERS: corporate_code and use_points were 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 →
Request
curl -X GET "https://api.stayapi.com/v1/marriott/bonvoy/price-calendar?property_id=LAXJW&date_from=2026-11-01&date_to=2026-11-05&nights=1&corporate_code=MMP" \
  -H "X-API-Key: YOUR_API_KEY"
Response
{
  "success": true,
  "property_id": "LAXJW",
  "date_from": "2026-11-01",
  "date_to": "2026-11-05",
  "nights": 1,
  "corporate_code": "MMP",
  "use_points": false,
  "currency": "USD",
  "available_count": 4,
  "dates": [
    { "date": "2026-11-01", "check_out": "2026-11-02", "available": true, "per_night": 129.0, "stay_total": 129.0, "currency": "USD", "points_total": null },
    { "date": "2026-11-02", "check_out": "2026-11-03", "available": true, "per_night": 471.0, "stay_total": 471.0, "currency": "USD", "points_total": null },
    { "date": "2026-11-03", "check_out": "2026-11-04", "available": true, "per_night": 535.0, "stay_total": 535.0, "currency": "USD", "points_total": null },
    { "date": "2026-11-04", "check_out": "2026-11-05", "available": false, "per_night": null, "stay_total": null, "currency": null, "points_total": null },
    { "date": "2026-11-05", "check_out": "2026-11-06", "available": true, "per_night": 129.0, "stay_total": 129.0, "currency": "USD", "points_total": null }
  ]
}