Searching and booking stays

Stays follow the standard four-step flow: search → fares → build → book.
Search and fares stream results as Server-Sent Events (SSE); build and book
return JSON. All requests require the consumer HMAC and a traveler bearer
token — omitted from the snippets below for brevity.

("Stays" is Mercury's canonical name for lodging — hotels, apartments, and other
accommodation.)

1. Look up destinations

Resolve free-text input to destination and property identifiers.

GET /v1/stays/destinations?q=rome&limit=5

Queries shorter than two characters return an empty result. See the
API Reference for the response shape.

2. Search

POST /v1/stays/search streams stay solutions for a destination and date range
as SSE. If the requested stay exceeds the configured maximum nights, the stream
terminates with event: error and code MAX_NIGHTS_EXCEEDED; other provider
failures use PROVIDER_ERROR.

Request body (StaySearchRequest) — provide either a destination or a
specific property:

{
  "destination": "rome-city-id",
  "checkIn": "2026-02-10",
  "checkOut": "2026-02-12",
  "rooms": [{ "adults": 2, "childrenAges": [] }],
  "passengers": { "adults": 2 },
  "nationality": "IT"
}

Each streamed solution's id is the searchSolutionId for the next step.

3. List fares

POST /v1/stays/fares streams the bookable room fares for a chosen solution.

Request body (StayFaresBody):

{
  "searchSolutionId": "018f...",
  "checkIn": "2026-02-10",
  "checkOut": "2026-02-12",
  "rooms": [{ "adults": 2, "childrenAges": [] }],
  "isPersonal": false
}

External fares are withheld by default. Pay-at-property (external) fares
are not surfaced unless your environment enables them. Fares returned here are
prepaid through BizAway.

4. Build the fare

POST /v1/stays/fares/build locks a specific fare and returns it as JSON
(201).

Request body (StayBuildFareBody):

{ "fareId": "018f...", "searchSolutionId": "018f...", "isPersonal": false }

The response carries a totalPrice as { "amount": "320.00", "currency": "EUR" }. See the API Reference for the full fare shape.

5. (Optional) Protection plans

GET /v1/stays/fares/{fare_id}/protection-plans

6. Book

POST /v1/stays/bookings creates the booking from the built fareId. Send a
unique Idempotency-Key header (required — see
Bookings and trips).

Request body (BookStayRequest):

{
  "fareId": "018f...",
  "passengers": [
    {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "type": "adult",
      "isHolder": true
    }
  ],
  "isPersonal": false,
  "tripId": null
}

For stays, the booking holder's phone number is taken from the authenticated
traveler's profile. Manage the booking lifecycle with the shared endpoints in
Bookings and trips.

See the API Reference for the complete request and
response schemas.

Reporting issues

This page is maintained by the BizAway integration team. To request changes or
report an error, contact your BizAway integration contact. Edits made directly
in the ReadMe dashboard are overwritten on the next publish.