Create a trip

Create a new trip for the authenticated traveler. When bookingId is supplied the booking is atomically associated with the new trip; purpose is derived from booking metadata when omitted.

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

Request body for creating a trip.

Two usage modes:

  • Direct — supply purpose (and optionally startsAt/endsAt)
    with no bookingId. The supplied value is stored as the traveler's
    custom label (purpose, so later booking facts never retitle it) and
    as defaultPurpose; clearing purpose via PATCH reverts to the
    automatic title.
  • Booking-linked — supply bookingId to atomically create a trip and
    associate an existing standalone booking. defaultPurpose is set to the
    booking's destination city. purpose, when non-blank, is stored as the
    traveler's initial custom label and immediately reflected in responses.
    bookingId is the Mercury Booking.id UUID.

A future ticket will introduce a stages field aligned with the
MER-449 trip-stage shape. The pre-MER-449 segments field has been
removed — use POST /v1/trips/{tripId}/bookings to attach bookings
after creation.

Initial trip name. Required when bookingId is absent; stored as the traveler's custom label (purpose) and as defaultPurpose. When bookingId is present, defaultPurpose is derived from the booking's destination city; this field, when non-blank, is stored as the traveler's initial custom label (purpose) and is immediately reflected in responses.

Mercury Booking.id UUID. When provided, the booking is atomically associated with the newly created trip.

Responses

403

Booking owned by a different user

404

Booking not found

409

Booking already associated with a trip. The error body carries existingTripId so the client can navigate to that trip.

503

Database unavailable

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