Create a stay booking (with optional protection plan)

Create a stay booking from a locked fare. Accepts the same fields as POST /v1/{vertical}/bookings plus an optional insuranceQuotes list of Mercury protection-plan UUIDs from GET /v1/stays/fares/{fareId}/protection-plans.

Quote UUIDs are translated to provider IDs before forwarding. A stale or unknown UUID results in 410 QUOTE_EXPIRED.

The Idempotency-Key header is required.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Request body for POST /v1/stays/bookings (MER-761).

Stays-only booking creation request. Extends
:class:CreateBookingRequest with insuranceQuotes — a list of Mercury
protection-plan UUIDs obtained from
GET /v1/stays/fares/{fareId}/protection-plans — and rooms — an
optional per-room guest allocation for multi-room bookings.

fareId is the canonical locked-fare identifier (Mercury UUID from
POST /v1/stays/fares/build). tripId optionally associates the
booking with an existing trip.

UUIDs in insuranceQuotes are translated to provider quote IDs before
forwarding. A stale or unrecognised UUID results in 410 QUOTE_EXPIRED.

This schema is intentionally limited to POST /v1/stays/bookings so
that insuranceQuotes and rooms do not appear in the OpenAPI
schemas for flights, trains, or cars.

string
required

Locked fare ID from the search session.

passengers
array of objects

Passenger details. Exactly one adult must have isHolder=true.

Passengers
extraServices
array of objects
deprecated

Deprecated: send all ancillary selections via ancillaries. Still accepted for back-compat; ancillaries takes precedence.

Extraservices
array | null

Unified ancillary selection input. Each item: {id, quantity, passenger_id}. Takes precedence over extraServices when both are provided. For cars, both booking-flow and pay-at-desk selections go here; Mercury routes each to the correct provider bucket by its ancillary kind, so requestServices is no longer needed.

requestServices
array of objects
deprecated

Deprecated (cars only): pay-at-desk selections now belong in the unified ancillaries field, which Mercury routes by ancillary kind. Still accepted for back-compat.

Requestservices

Optional trip to associate this booking with. When provided, a TripSegment record is persisted linking the booking to the trip.

Whether this is a personal (non-business) booking.

Contact phone number for the booking.

Invoice profile to use for this booking. Auto-resolved when omitted.

Billing address to associate with this booking. Auto-resolved from the invoice profile when omitted.

object | null

Answers to the account's custom fields for this vertical, keyed by definition key (from GET /v1/custom-fields). Values: string for text/single_select (option key) and date (YYYY-MM-DD), list of option keys for multi_select. Answers are validated against the account's definitions; any invalid answer fails the request with a field-level 422. An empty value ("" or []) means unanswered and is stripped at the boundary, so it is treated identically to omitting the key.

array | null

Optional list of protection-plan Mercury UUIDs from GET /v1/stays/fares/{fareId}/protection-plans. UUIDs are translated to provider quote IDs before forwarding.

array | null

Optional per-room guest allocation for a multi-room stay booking. Each entry lists the passengers indices assigned to that room, mirroring StaySearchRequest.rooms from search so a client can carry its search-time room split into the booking. Omit for a single-room booking — identical wire behaviour to today. When provided, every adult in passengers must be referenced by exactly one room, and exactly one referenced passenger must have isHolder=true.

Headers

Client-generated idempotency key (UUID v4 recommended). Required on all booking mutation requests.

Responses

401

Missing or invalid authentication

403

User lacks booking capability for this vertical

404

Fare not found or expired / trip not accessible

409

Booking already exists (conflict)

410

Protection plan quote expired; re-fetch quotes

422

Validation error, missing passenger document, or missing Idempotency-Key

503

Booking service not configured

Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json