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.

Why the traveler is booking outside travel policy, as typed at checkout. Stored on the booking and returned as policyJustification on its detail. Optional; blank counts as missing. It does not answer a confirm that asks for a reason: send that on the confirm request.

The taskId of the traveler's quote request (the requestQuote TIE task) when the booking is made from one of its quoted options in the quote's checkout. Once the booking is created, Mercury ends that task as customer_accepted and links it to the booking; no chat acceptance or device confirmation is involved. A task that is not the caller's, is not a quote request, or has already ended is ignored: the booking is created either way. Omit it for any other booking.

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