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. Omitting the key and sending an explicit null are equivalent: Mercury resolves both to the account's first available invoice profile (the same list GET /v1/invoice-profiles/booking returns) before the request reaches the provider, so neither shape is ever forwarded to the provider as a null or missing value. A client that has already defaulted this field to null (for example a generated TypeScript client with no way to omit an optional key it has serialized) still gets auto-resolution — it does not need to strip the key to opt in. When the account has no invoice profile at all, booking creation fails with a 422 NO_INVOICE_PROFILE error before any provider call is made — no booking is created and no fiscal documents are issued. Do not assume a newly created guest-checkout account (from the magic-link exchange) has a default invoice profile at the moment of its first booking — Mercury's own account provisioning does not create one, so that first booking should be expected to hit this error unless a real invoiceProfileId is supplied explicitly. Whichever profile is resolved cannot be changed after create — there is no way to point an existing booking at a different profile. Whether an edit to this profile (PATCH /v1/invoice-profiles/{id}) made after this booking is created — including appending an emailRecipients entry — is reflected in the invoice this booking eventually generates is not currently documented or guaranteed. Do not design a flow that depends on a post-create edit reaching this booking's invoice.

Billing address to associate with this booking. Omitting the key and sending an explicit null are equivalent, following the same null-as-absent rule as invoiceProfileId: both are resolved from the resolved invoice profile's default billing address before the request reaches the provider. That defaulting applies to stays and flights; for cars and trains the key is left off the request to the provider entirely rather than sent as null.

A flight booking needs a billing address to be confirmed. The provider requires one to finalize and reports it missing only at POST /v1/flights/bookings/{id}/confirm, by which point the booking already exists and can never be confirmed. So when a flight create resolves no billing address — none sent here, and the resolved invoice profile has no default — it fails with 422 BILLING_ADDRESS_REQUIRED (recoveryAction: FIX_INPUT, field error on this field) before any provider call, and no booking is created. Send a billingAddressId from GET /v1/billing/addresses, or an invoiceProfileId whose defaultBillingAddressId is set. A newly provisioned guest-checkout account has neither, so a guest flight booking must supply this field. Cars, trains and stays are not subject to this check.

A message for the approver, for a traveler whose company requires one on bookings that need approval (see approvalMessageRequired on GET /v1/profile/identity). Passed on to the approver, stored on the booking and returned as approvalMessage on its detail. Optional; blank counts as missing. When the company requires one and it is missing, create fails with 422 APPROVAL_MESSAGE_REQUIRED.

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.

Client-generated idempotency key (UUID v4 recommended). Required on all booking mutation requests. Whether a repeated key replays the first response depends on the operation; see its description and the idempotency and retries guide.