Hotels

GET/v1/hotels/{hotelId}/rates

The bookable rates of one hotel — billable

The step between a search result and a booking. The search gives one indicative price per hotel; this asks the supplier what can actually be booked for those dates and returns the rateId that POST /v1/hotels/bookings expects.

The price here may differ from the one in the search. That is not a defect — a real availability check happens in between. When it differs materially, priceNotice says so instead of quietly showing the higher number.

Auth: API key
Scope: hotels:search
Rate limit: SEARCH
Search quota: Counts
Idempotency: Not required

Path parameters

Parameter	Type	Required	Description
`hotelId`	`string`	Required

Query parameters

Parameter	Type	Required	Description	Example
`checkIn`	`string`	Optional		`2026-11-02`
`checkOut`	`string`	Optional		`2026-11-06`
`adults`	`number`	Optional		`2`
`children`	`number`	Optional
`rooms`	`number`	Optional
`residency`	`string`	Optional	The guest's country of residence. Some rates are only sold to some markets.	`de`
`language`	`string`	Optional		`en`

Responses

200 · HotelRatesDto

Errors

Every one of these carries the same envelope. What each error.type means, and whether a retry can succeed, is on the error index — once, for all operations.

Status	When
`401`	No key, or an invalid, revoked or expired key, or a valid key sent to the other environment. `error.type` tells them apart: `authentication_required`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`. On `wrong_environment` the key is fine and the base URL is not — a `vcb_live_…` key was sent to the sandbox host or a `vcb_test_…` key to the live host; `error.gatewayEnvironment` names the host, `error.keyEnvironment` the key. Do not rotate the key, change the URL.
`403`	The key is not allowed to do this. On `insufficient_scope`, `error.missingScope` names the missing scope; on `ip_not_allowed` the request came from an address outside the allowlist.
`429`	Quota exhausted. `Retry-After` and `error.retryAfter` give the wait in seconds. This response MAY be retried — after the stated time.
`500`	A failure on our side. The `requestId` in the response belongs in every support request.
`503`	A supplier is unreachable (`upstream_unavailable`). May be retried, with growing backoff.

Response headers

Set on every response of this operation, successful or not.

Header	Type	Meaning
`X-RateLimit-Limit`	`integer`	Upper limit of the class that applied to this request.
`X-RateLimit-Remaining`	`integer`	Remaining requests in the running window.
`X-RateLimit-Reset`	`integer`	Unix time at which the window starts anew.
`X-Request-Id`	`string (uuid)`	Identifier of this request. Quote it in any support request — including on a successful response, in case the outcome becomes questionable later.

Example

GET /v1/hotels/{hotelId}/rates

curl -sS "$VACABEE_API_URL/v1/hotels/<hotelId>/rates" \
  -H "Authorization: Bearer $VACABEE_API_KEY"

Set VACABEE_API_URL to https://api.vacabee.com with a live key, or to https://sandbox-api.vacabee.com with a vcb_test_ key. Binding a host to one kind of key is planned and is not enforced by the host yet, so nothing stops a key from being answered at the wrong base URL — assert the prefix against your configured URL yourself. What the sandbox answers

TypeScript SDK

await vacabee.hotels.rates(…);

The typed method sends the right headers, derives the idempotency key where one is required, and returns the response type generated from this document. Installing and using the SDK