Create a booking

post

https://example.com/v1/{vertical}/bookings

Create a booking from a locked fare. fareId must come from GET /v1/{vertical}/search/{sessionId}/fares/{fareId}.

When tripId is supplied, a TripSegment record is persisted linking this booking to its parent trip.

The Idempotency-Key header is required to prevent duplicate bookings on network retry.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

vertical

string

enum

required

Allowed:

Body Params

Request body for creating a booking.

fareId must be a locked fare ID returned by
GET /v1/{vertical}/search/{sessionId}/fares/{fareId}.

The Idempotency-Key header is required. Sending the same key
twice on a failed network retry returns the original response without
creating a duplicate booking.

fareId

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

ancillaries

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

tripId

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

isPersonal

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

phone

Contact phone number for the booking.

invoiceProfileId

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

billingAddressId

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

customFields

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.

Headers

Idempotency-Key

Client-generated idempotency key (UUID v4 recommended). Required on all booking mutation requests to prevent duplicate bookings on retry.

Responses

401

Missing or invalid authentication

403

User lacks booking capability for this vertical

404

Referenced fare or tripId does not exist / is not accessible to the authenticated account

409

Booking already exists (conflict)

410

Offer expired (OFFER_EXPIRED); refresh fare search

422

Validation error, missing Idempotency-Key header, missing passenger document, or required custom attributes were not supplied

503

Booking service not configured

Language

Credentials

Loading…

Response

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

application/json

201Successful Response