Browse documentation
GET

Hotel Prices API

Point of sale and display settings

Pass market=ES for Spain (Spanish and EUR defaults) or market=US for the United States (English and USD). The optional language and currency parameters override these defaults. Market is an ISO 3166-1 two-letter country code; unknown codes and conflicting market/country_market values return 400.

Legacy country_market remains supported and keeps English/USD defaults. Omitting both retains US targeting and English/USD. For search by URL, explicit language/currency query parameters override values embedded in the URL; explicit URL values override market defaults.

Defaults: ES es/EUR, US en-us/USD, GB en-gb/GBP, DE de/EUR, FR fr/EUR, IT it/EUR, PT pt-pt/EUR, NL nl/EUR, IE en-gb/EUR, CA en-us/CAD, AU en-gb/AUD, JP ja/JPY. Other valid countries use en-us/USD unless overridden.

data.effective_market reports requested_country, nullable targeted_country, language, and currency. Targeting is best-effort: country_verified is false and verified_country is null because the response does not independently verify geography. A null target means country targeting was not applied. MCP returns the same object as effective_market.

{"requested_country":"ES","targeted_country":"ES","country_verified":false,"verified_country":null,"language":"es","currency":"EUR"}

For prices, total_price_value follows the displayed gross basis and is not guaranteed to include every charge. taxes_and_charges_value is the included portion (gross minus net); inspect tax_breakdown[].included for excluded taxes.

Compare the same stay, occupancy, room, rate conditions and currency. Market can change tax inclusion and displayed totals without changing the all-in price; it does not guarantee a discount or availability. In the verified Spain/US comparison, the same rate displayed US$455 including taxes in Spain and $341 excluding taxes in the US, with the same $455.46 all-in amount.

Get real-time room pricing, tax breakdowns, and availability for any Booking.com hotel.

Overview

Live Pricing Data

Returns real-time prices with tax breakdowns, cancellation policies, meal plans, and bundle extras for all available rooms.

The Hotel Prices endpoint provides comprehensive pricing information for a specific Booking.com hotel, including per-night and total costs, detailed tax breakdowns, and individual room options with cancellation policies and meal plans.

Sold-out stays

A stay that is independently confirmed as sold out returns HTTP 200 with is_soldout: true, rooms: [], and available_rooms_count: 0. If empty inventory cannot be confirmed as sold out, the API returns a 502 instead of guessing.

Endpoint URL

GET https://api.stayapi.com/v1/booking/hotel/prices

Query Parameters

Parameter Type Required Description
hotel_id string Required Booking.com hotel ID (numeric, up to 10 digits)
check_in string Required Check-in date (YYYY-MM-DD)
check_out string Required Check-out date (YYYY-MM-DD)
adults integer Optional Number of adults (1-10, default: 2)
rooms integer Optional Number of rooms (1-10, default: 1)
currency string Optional 3-letter currency override (market default, otherwise USD)
country_market string (ISO-3166) Optional Legacy two-letter country target (default: US), preserving English/USD defaults. It must match market if both are supplied. The echo is a request value, not verified geography.
children integer Optional Number of children, 0–10; default 0. Supply one age per child.
children_ages string Optional Comma-separated integer ages 0–17, for example 5,8. Required when children is positive; the age count must equal children. Omit or leave empty for zero children.

Response Structure

Pricing Summary

Shows the cheapest available room. See the rooms array for all room categories and prices.

  • price_per_night / price_per_night_value - Formatted and numeric price per night
  • total_price / total_price_value - Total stay cost
  • net_price / net_price_value - Price before taxes
  • taxes_and_charges / taxes_and_charges_value - Tax total
  • currency - Currency code

Tax Breakdown

  • name - Tax name
  • type - Tax type
  • percentage - Tax rate
  • amount / amount_value - Tax amount
  • included - Whether tax is already included in the price

Rooms

Array of all available room categories with individual pricing. Each entry represents a bookable room option.

  • block_id / room_name - Room identifier and name
  • is_refundable / cancellation_policy - Cancellation details
  • breakfast_included / meal_plan - Meal information
  • price_per_night / total_price - Room-level pricing
  • bundle_extras - Included extras (WiFi, gym, etc.)

Sold-out response

Confirmed sold-out dates use the normal success schema: is_soldout is true, rooms is empty, and available_rooms_count is zero. Pricing summary values are null because there is no bookable rate.

Best Practices

Date Selection

Prices vary significantly by date. Always provide accurate check-in/check-out dates to get reliable pricing.

Implementation Tips

  • Use both formatted strings and numeric values for flexible display
  • Check is_soldout before displaying pricing
  • Display the tax breakdown for price transparency
  • Highlight cancellation policies prominently for user confidence

Error handling and status codes

Status codes: 200 on success; errors use non-2xx (400, 500, 502) with Problem Details.

  • 400 INVALID_HOTEL_ID: Hotel ID is not numeric or exceeds 10 digits.
  • 400 INVALID_DATE_FORMAT: Dates are not in YYYY-MM-DD format.
  • 400 INVALID_DATES: Check-out is before check-in or stay exceeds 90 nights.
  • 400 INVALID_CURRENCY: Currency is not a 3-letter code.
  • 502 UPSTREAM_ERROR: Upstream request or parsing failed, including empty inventory that could not be confirmed as sold out.
  • 500 INTERNAL_ERROR: Unexpected processing error.

Error responses (Problem Details)

All Booking.com hotel endpoints return errors using RFC 7807 Problem Details.

{
  "type": "https://api.stayapi.com/errors/invalid-url",
  "title": "Invalid URL",
  "status": 400,
  "detail": "Parameter 'url' must be a full Booking.com hotel URL of the form https://www.booking.com/hotel/{cc}/{slug}.html.",
  "error_code": "INVALID_URL",
  "provided": "baan-coconut"
}

Media type: application/problem+json

Standard fields: type, title, status, detail

Extensions: error_code and any endpoint-specific fields

2xx policy: 2xx is returned only when data extraction succeeds.

Family occupancy

For two adults and a child aged eight, send adults=2&children=1&children_ages=8. Multiple ages use a single CSV value, for example children=2&children_ages=5%2C8. Missing ages, count mismatches, noninteger ages and ages outside 0–17 return HTTP 400 Problem Details with error_code: INVALID_OCCUPANCY. Invalid count types or counts outside 0–10 return HTTP 422. Adults-only requests can omit both child parameters.

Each data.rooms[] includes fits_requested_occupancy: true means that one rate accommodates the entire requested party, false means it does not, and null means the fit is unknown. Room alternatives may accommodate only part of your party. The prices summary selects a verified full-family rate; if none can be verified, prices returns HTTP 502 instead of a misleading family quote. Prices describe one room for the stay, not a combined multiroom reservation total. The rooms parameter does not establish an allocation of guests across rooms.

Rate labels

data.pricing_summary and each data.rooms[] item includes labels (an array of readable strings), genius_discount_pct (a number or null), and is_mobile_rate (a boolean). Labels describe the quoted rate, for example Mobile rate or Bonus savings. Unlabelled rates return [].

These are anonymous public quotes. A property Genius badge alone does not prove a Genius discount on this rate. A null percentage means no rate-specific percentage was observed; is_mobile_rate: false means no explicit mobile-rate marker was observed. Labels can vary by market and occupancy and do not guarantee eligibility for logged-in member prices. Existing discount fields remain available.

Request
curl -X GET "https://api.stayapi.com/v1/booking/hotel/prices?hotel_id=346648&check_in=2027-05-15&check_out=2027-05-17&adults=2&children=1&children_ages=8&rooms=1&currency=USD" \
  -H "x-api-key: YOUR_API_KEY"
Response
{
  "success": true,
  "hotel_id": "346648",
  "data": {
    "hotel": {
      "id": "346648",
      "name": "Angsana Laguna Phuket"
    },
    "search_params": {
      "check_in": "2027-05-15",
      "check_out": "2027-05-17",
      "adults": 2,
      "children": 1,
      "children_ages": [
        8
      ],
      "rooms": 1,
      "currency": "USD",
      "nights": 2
    },
    "pricing_summary": {
      "price_per_night": "$185",
      "price_per_night_value": 185.0,
      "total_price": "$370",
      "total_price_value": 370.0,
      "net_price": "$320",
      "net_price_value": 320.0,
      "taxes_and_charges": "$50",
      "taxes_and_charges_value": 50.0,
      "currency": "USD",
      "labels": [
        "Mobile rate"
      ],
      "genius_discount_pct": null,
      "is_mobile_rate": true
    },
    "tax_breakdown": [],
    "rooms": [
      {
        "price_per_night": "$185",
        "price_per_night_value": 185.0,
        "total_price": "$370",
        "total_price_value": 370.0,
        "net_price": "$320",
        "net_price_value": 320.0,
        "taxes_and_charges": "$50",
        "taxes_and_charges_value": 50.0,
        "currency": "USD",
        "labels": [
          "Mobile rate"
        ],
        "genius_discount_pct": null,
        "is_mobile_rate": true,
        "block_id": "34664801_1",
        "room_id": "34664801",
        "room_name": "Family Suite",
        "max_occupancy": 3,
        "breakfast_included": false,
        "meal_plan": null,
        "is_refundable": true,
        "fits_requested_occupancy": true
      },
      {
        "price_per_night": "$142",
        "price_per_night_value": 142.0,
        "total_price": "$284",
        "total_price_value": 284.0,
        "net_price": "$240",
        "net_price_value": 240.0,
        "taxes_and_charges": "$44",
        "taxes_and_charges_value": 44.0,
        "currency": "USD",
        "labels": [
          "Mobile rate"
        ],
        "genius_discount_pct": null,
        "is_mobile_rate": true,
        "block_id": "34664802_1",
        "room_id": "34664802",
        "room_name": "Double Room",
        "max_occupancy": 2,
        "breakfast_included": false,
        "meal_plan": null,
        "is_refundable": true,
        "fits_requested_occupancy": false
      }
    ],
    "available_rooms_count": 2,
    "is_soldout": false
  },
  "message": "Success"
}