Hilton Rooms API - Cash Rates and Reward Points
Get dated room types with starting cash offers and available full-points rewards.
Copy for your AI agent
Paste into Claude, ChatGPT, Cursor or Copilot — endpoint, parameters, response fields and a curl example in Markdown.
Overview
Get Hilton room types, starting cash rates, and full-points rewards with StayAPI. Compare exact stay totals and dated nightly points for standard and premium rewards.
Scope
Use hotel_code from Search or URL to ID. One room with no children is fixed. pricing_scope is starting_rates for cash offers, not a full cash rate-plan list. reward_rates contains available standard and premium full-points offers, not Points & Money quotes. Quotes are available without a Hilton login; members_only and login_required describe booking requirements. Amounts and availability can change before booking. Confirmed unavailability returns HTTP 200 with availability_status unavailable, room_types [], and total 0. This does not identify the reason rooms are unavailable. Unknown or failed responses remain non-2xx errors.
Authentication
Send your StayAPI key in the X-API-Key header. Successful requests return JSON; failures use RFC 7807 Problem Details.
Endpoint URL
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| hotel_code | string | Required | Exactly seven letters or digits, from Search or URL to ID. Returned uppercase. |
| check_in | date | Required | Valid YYYY-MM-DD date, today or later. |
| check_out | date | Required | Valid YYYY-MM-DD date after check_in. |
| adults | integer | Optional | 1 to 4 adults. Default: 2. One room and no children. |
| currency | enum | Optional | USD or GBP display currency. Default: USD. |
Response schema
| Field | Type | Description |
|---|---|---|
| success / hotel_code / check_in / check_out / adults | mixed | Successful request and normalized stay context. |
| currency / native_currency | string / nullable string | Requested display currency and Hilton source currency, respectively. native_currency may be null when unavailable. |
| availability_status | enum | available or unavailable. Confirmed unavailability is a successful response with no room types. |
| availability_message | nullable string | Null when available; No rooms are available for the requested dates. when unavailable. |
| pricing_scope | string | Always starting_rates: cash offers are starting rates; reward_rates is a separate full-points list. |
| total | integer | Number of available room types returned, not a room count. |
| room_types | array | Available room code, name, description, nullable occupancy, beds, accessible and suite flags, photos, rates, and reward_rates. A reward-only room can have rates: []. |
| room_types[].rates[].rate_plan_code | string | Identifier of the starting cash offer. |
| room_types[].rates[].per_night | number | Average nightly display amount for the stay. |
| room_types[].rates[].total / total_formatted | number / string | Exact published stay total. Do not multiply the rounded per_night amount to calculate it. |
| room_types[].rates[].currency | string | Display currency of the offer. |
| room_types[].rates[].includes_taxes_and_service_charges | boolean | Published tax-and-service-charge indicator; does not establish treatment of every possible property fee. |
| room_types[].rates[].rate_changes_during_stay | boolean | Whether the published rate changes during the stay. |
| room_types[].reward_rates | array | Available full-points offers. An empty array means no full-points offers were returned for this room in a successful response. |
| room_types[].reward_rates[].rate_plan_code / name | string | Reward offer identifier and published name. |
| room_types[].reward_rates[].reward_type | string | standard or premium. |
| room_types[].reward_rates[].points | integer | First-night points, not a nightly average. Do not multiply by the number of nights. |
| room_types[].reward_rates[].points_total | integer | Exact full-stay points total. |
| room_types[].reward_rates[].nightly_rates | array | Dated nightly breakdown: each entry contains date (YYYY-MM-DD) and points. Nights can have different points prices. |
| room_types[].reward_rates[].members_only / login_required | boolean | Hilton membership and login requirements for booking; these do not require a Hilton login to obtain the quote. |
Errors and limitations
Errors use RFC 7807 Problem Details with provider: "hilton" and a correlation id.
- 400 INVALID_INPUT: invalid search form, hotel code, dates, occupancy, or currency.
- 400 INVALID_URL: supply a canonical HTTPS Hilton hotel or reservation rooms URL.
- 422: a required parameter is missing or a typed parameter is outside its declared contract.
- 502 UPSTREAM_ERROR: Hilton data could not be retrieved or verified. An unverified sold-out rooms result also returns an error.
- 504: the request timed out.
- 503: service temporarily unavailable; honor Retry-After when supplied.