GET # Marriott Bonvoy Rooms API Get room types and rates for a specific Marriott Bonvoy property with real-time availability. ## Overview #### Property Code Required Use the property\_id from the Search endpoint (e.g., "BKKDT", "LAXJW") to fetch rooms for a specific hotel. The Marriott Bonvoy Rooms endpoint returns available room types with detailed rate plans, bed types, cancellation policies, and Bonvoy member-only pricing. Use this after the Search endpoint to get complete room-level details for a property. ### Endpoint URL GET https://api.stayapi.com/v1/marriott/bonvoy/rooms ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | property\_id | string | Required | Marriott property code (e.g., "BKKDT", "LAXJW") | | check\_in | string | Required | Check-in date in YYYY-MM-DD format | | check\_out | string | Required | Check-out date in YYYY-MM-DD format | | adults | integer | Optional | Number of adults (1-10). Default: 2 | | rooms | integer | Optional | Number of rooms (1-8). Default: 1 | | currency | string | Optional | Currency code (e.g., USD, EUR, GBP). Default: USD | | corporate\_code | string | Optional | Corporate or promotional rate code (e.g., MMP, AAA). | #### Property Codes Get property codes from the Search endpoint. Each hotel in the search response includes a property\_id field you can use here. ## Response Format The response includes room types grouped by category, each containing one or more rate plans with pricing and cancellation details. ### Response Structure - **success** : Boolean indicating request success - **property\_id** : The requested property code - **room\_types** : Array of room type objects - **total** : Total number of room types available ## Room Type Fields | Field | Type | Description | | --- | --- | --- | | name | string | Room type name (e.g., "Deluxe Room", "Executive Suite") | | bed\_type | string | Bed configuration (e.g., "1 King", "2 Double") | | view | string | Room view (e.g., "City View", "Pool View") | | category | string | Room category (e.g., "STANDARD", "SUITE") | | available\_rooms | integer or null | Number of rooms still available, or null when not provided | | rates | array | Array of rate plan objects (see below) | ## Rate Plan Fields | Field | Type | Description | | --- | --- | --- | | name | string | Rate plan name (e.g., "Best Available Rate", "Member Rate") | | rate\_plan\_code | string | Rate plan identifier. Use this to distinguish plans within a room type; names may repeat. | | per\_night | float or null | Cash room rate for the check-in night only, or null when unavailable. Nightly rates vary; see `nightly_rates`, and use `total` for the stay. Null for ACRS rates on multi-night stays | | total | float | Total cash price for the stay including taxes and fees (cash rates). Award rates also carry a cash figure Marriott attaches to the product; it is not the award price, use `points_total` | | fees | float | Additional fees | | currency | string | Currency code | | members\_only | boolean | Whether rate requires Bonvoy membership | | free\_cancellation\_until | string or null | Free cancellation deadline (ISO 8601 datetime), or null when not provided | | points | integer or null | Bonvoy points for the check-in night only; null for cash-only rates. Not a stay total; use `points_total`. Null for ACRS rates on multi-night stays | | points\_total | integer or null | Bonvoy points for the whole stay; null for cash-only rates. Equals the sum of `nightly_rates[].points` when the breakdown is present | | points\_saved | integer or null | Points saved vs standard redemption (when available) | | free\_nights | integer or null | Number of free nights included in points redemption | | nightly\_rates | array | Per-night breakdown in stay order, one object per night: `date` (YYYY-MM-DD), `cash` (room rate before taxes and fees, or null), `points` (integer or null), `free_night` (boolean). Empty for ACRS rates | | source\_of\_rate | string or null | Marriott reservation system behind the rate: `MARSHA` (legacy) or `ACRS` (new) | ### ACRS hotels Marriott is moving hotels from its legacy MARSHA reservation system to ACRS. ACRS hotels are returned the same way, with `source_of_rate: "ACRS"` and these differences: - Rate plan and room codes differ from MARSHA ones and are longer (for example `RETAIL`, `MEM5TT76`, `MAREXP`) - There is no per-night breakdown: `nightly_rates` is empty. On multi-night stays `per_night` and `points` are null; use `total` and `points_total` - Room names include the room description (for example "1 King Bed, Hearing Accessible"), so accessible variants are distinguishable ## Error Responses The API returns standard HTTP error codes with detailed error messages following the RFC 7807 Problem Details format. ### 400 Bad Request Invalid request parameters (e.g., invalid dates, missing property\_id) ``` { "type": "https://api.stayapi.com/errors/invalid-dates", "title": "Invalid Dates", "status": 400, "detail": "Check-out date must be after check-in date" } ``` ### 404 Not Found `PROPERTY_NOT_FOUND`: no Marriott property matches the `property_id`. ``` { "type": "https://api.stayapi.com/errors/property-not-found", "title": "Property Not Found", "status": 404, "detail": "Marriott property ZZZQX not found", "error_code": "PROPERTY_NOT_FOUND" } ``` ### 502 Bad Gateway Upstream service error from Marriott; usually transient, worth one retry after a few seconds ``` { "type": "https://api.stayapi.com/errors/upstream-error", "title": "Upstream Error", "status": 502, "detail": "The upstream service could not complete the request.", "error_code": "UPSTREAM_ERROR" } ``` ### 502 Upstream Property Rejected Marriott's room-rate services rejected the `property_id` ("Invalid Property Code") and Marriott could not complete the lookup. Retry later; the [price calendar](/docs/endpoints/marriott-bonvoy/price-calendar) may still price the property ``` { "type": "https://api.stayapi.com/errors/upstream-property-rejected", "title": "Upstream Property Rejected", "status": 502, "detail": "The upstream service could not complete the request.", "error_code": "UPSTREAM_PROPERTY_REJECTED" } ``` ## Usage Tips ### Best Practices - Get the `property_id` from the Search endpoint first - Each room type may have multiple rate plans with different prices and policies - Check `members_only` to identify Bonvoy member-exclusive rates - Use `free_cancellation_until` to show flexible booking options - Rates bookable with Bonvoy points include `points`, `points_total`, `points_saved`, and `free_nights` fields - For multi-night stays use `points_total` or sum `nightly_rates`. `points` and `per_night` are the check-in night only and nightly prices vary by day of week - The same room can list several award rate plans (for example two "Redemption with Points Upgrade" plans at different prices), so key on `rate_plan_code`, not on the rate name - Check `available_rooms` when provided; null means inventory counts are unavailable. - For ACRS hotels (`source_of_rate: "ACRS"`) use `total` and `points_total` for multi-night stays; there is no per-night breakdown #### Rate Limiting This endpoint is subject to your plan's rate limits. Each request counts as one API call regardless of the number of room types returned. ## Related Endpoints ### Marriott Bonvoy Search Search for Marriott hotels by coordinates to get property codes [View Documentation →](/docs/endpoints/marriott-bonvoy/search) ### Marriott Bonvoy Price Calendar Find the cheapest check-in dates before requesting rooms [View Documentation →](/docs/endpoints/marriott-bonvoy/price-calendar) ### Meta Search Search across multiple booking platforms [View Documentation →](/docs/endpoints/meta-search) Request ```curl curl -X GET "https://api.stayapi.com/v1/marriott/bonvoy/rooms?property_id=BKKDT&check_in=2026-11-10&check_out=2026-11-13&adults=2¤cy=USD" \ -H "X-API-Key: YOUR_API_KEY" ``` Response ```json { "success": true, "property_id": "BKKDT", "room_types": [ { "name": "Deluxe Room", "bed_type": "1 King", "view": "City View", "category": "STANDARD", "available_rooms": 5, "rates": [ { "name": "Best Available Rate", "rate_plan_code": "BAR", "per_night": 185.00, "total": 555.00, "fees": 0, "currency": "USD", "members_only": false, "free_cancellation_until": "2026-11-08T18:00:00", "points": null, "points_total": null, "points_saved": null, "free_nights": null, "nightly_rates": [ {"date": "2026-11-10", "cash": 185.00, "points": null, "free_night": false}, {"date": "2026-11-11", "cash": 185.00, "points": null, "free_night": false}, {"date": "2026-11-12", "cash": 185.00, "points": null, "free_night": false} ], "source_of_rate": "MARSHA" }, { "name": "Member Rate", "rate_plan_code": "MBR", "per_night": 166.50, "total": 499.50, "fees": 0, "currency": "USD", "members_only": true, "free_cancellation_until": "2026-11-08T18:00:00", "points": null, "points_total": null, "points_saved": null, "free_nights": null, "nightly_rates": [ {"date": "2026-11-10", "cash": 166.50, "points": null, "free_night": false}, {"date": "2026-11-11", "cash": 166.50, "points": null, "free_night": false}, {"date": "2026-11-12", "cash": 166.50, "points": null, "free_night": false} ], "source_of_rate": "MARSHA" } ] }, { "name": "Executive Suite", "bed_type": "1 King", "view": "City View", "category": "SUITE", "available_rooms": 2, "rates": [ { "name": "Redemption", "rate_plan_code": "MRYA", "per_night": null, "total": 555.00, "fees": 0, "currency": "USD", "members_only": true, "free_cancellation_until": "2026-11-08T18:00:00", "points": 45000, "points_total": 125000, "points_saved": 0, "free_nights": 0, "nightly_rates": [ {"date": "2026-11-10", "cash": null, "points": 45000, "free_night": false}, {"date": "2026-11-11", "cash": null, "points": 45000, "free_night": false}, {"date": "2026-11-12", "cash": null, "points": 35000, "free_night": false} ], "source_of_rate": "MARSHA" } ] } ], "total": 2 } ``` ```json { "type": "https://api.stayapi.com/errors/invalid-date-format", "title": "Invalid Date Format", "status": 400, "detail": "Date must be in YYYY-MM-DD format", "instance": "/v1/marriott/bonvoy/rooms", "provider": "marriott", "product": "bonvoy", "error_code": "INVALID_DATE_FORMAT", "correlation_id": "req_abc123" } ```