Create a train booking

post

https://example.com/v1/trains/bookings

Create a train booking, optionally selecting BizzyFlex protection-plan quotes.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Trains-only booking creation request (MER-985).

Extends :class:CreateBookingRequest with two train-specific fields:

documentId — optional Mercury UUID of a stored travel document
from GET /v1/profile/documents. The document is validated for
ownership and its internal ID is forwarded as travel_document_id
on the booking holder passenger (required for document-mandatory
Trainline itineraries).
insuranceQuotes — optional list of Mercury BizzyFlex protection-plan
UUIDs obtained from GET /v1/trains/fares/{fareId}/protection-plans.

UUIDs in insuranceQuotes are translated to provider quote IDs at the
route boundary before forwarding; a stale or unrecognised UUID results in
410 QUOTE_EXPIRED before any booking is created (no orphan bookings).
After the booking is created Mercury issues a follow-up subscription
request to bind the selection (best-effort — subscription failures are
logged and swallowed so the booking response is still returned).

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

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.

documentId

Mercury UUID of a stored travel document (from GET /v1/profile/documents). When provided the document is validated for ownership and forwarded as travel_document_id on the holder passenger.

insuranceQuotes

array | null

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

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, or the provider rejected the forwarded travel-document credential

403

User lacks booking capability for this vertical, or the provider denied the travel-document lookup (resolved deny)

404

Fare not found or expired, or tripId inaccessible

409

Booking already exists (conflict)

410

Selected BizzyFlex quote has expired

422

Validation error, invalid documentId, missing passenger document, or missing header

503

Booking or travel document 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