Search stay fares (SSE stream)

post

https://example.com/v1/stays/fares

Stream stay fares for a stay solution. Accepts either Mercury UUIDs from a prior POST /v1/stays/search stream (searchSolutionId + propertyId) or a direct property block from autocomplete (no prior search required). Accepts either an authenticated bearer token or a guest session token. Unknown or expired search-stream identifiers return 410 OFFER_EXPIRED; a property with no rates for the requested dates streams an empty result (event: done). When the requested stay exceeds the configured maximum nights, the stream terminates with event: error and code MAX_NIGHTS_EXCEEDED (message includes the allowed maximum). Other provider failures use PROVIDER_ERROR.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

POST body for /v1/stays/fares.

Fares can be requested in one of two mutually exclusive ways:

Search-stream path — supply searchSolutionId and propertyId
(Mercury UUIDs emitted by POST /v1/stays/search). Requires a prior
search within the session cache TTL.
Direct property path — supply property (a
:class:StayPropertyDestination from autocomplete). Rates are looked up
directly from the property identifier, so Mercury streams fares straight
from the autocomplete propertyId without requiring a prior search.

Exactly one path must be provided; supplying both or neither returns
422 UNPROCESSABLE_ENTITY.

check_in / check_out / rooms are required (MER-873). They
carry the same trip context as the preceding POST /v1/stays/search
request (or the direct-property deep link) and clients re-send them
verbatim from their rateSelection step; Mercury never persists them
between the search and fares calls.

No past-date validator is applied to check_in / check_out:
:class:StaySearchRequest already enforces "not in the past" at search
time, and the fares route is a passthrough for the same trip dates.
Re-validating here would reject legitimate same-day fares calls that
cross UTC midnight after the search succeeded.

searchSolutionId

Search-solutions Mercury UUID from the search stream. Required together with top-level propertyId on the search-stream path; omit when using property.

propertyId

Property Mercury UUID from the search stream. Required together with searchSolutionId on the search-stream path; omit when using property (which carries the raw autocomplete propertyId instead).

property

StayPropertyDestination | null

Named-property destination from autocomplete for direct fares without a prior search. Mutually exclusive with searchSolutionId + top-level propertyId.

checkIn

date

required

Check-in date as YYYY-MM-DD. Must match the value supplied to the preceding POST /v1/stays/search request.

checkOut

date

required

Check-out date as YYYY-MM-DD. Must be strictly after checkIn and match the value supplied to the preceding POST /v1/stays/search request.

rooms

array of objects

required

length ≥ 1

Per-room occupancy. Must match the rooms supplied (or derived from passengers) on the preceding POST /v1/stays/search request.

Rooms*

solutionKey

SHA-256 solution key for lineage tracking.

isPersonal

boolean

Defaults to false

Booking profile: true for personal travel, false for business travel. Must match the bookingProfile supplied to the preceding POST /v1/stays/search request.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

401

Unauthenticated

410

Search session expired; refresh search

503

Provider unavailable

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200SSE stream

422Validation Error