Guides
  1. bookings-and-trips

Bookings and trips

Manage the booking lifecycle and organise bookings into trips.

Once you have built a fare (see the per-vertical guides), you create and manage
bookings through a shared set of endpoints, and organise them into trips.
All requests require the consumer HMAC and a traveler bearer
token.

Throughout, {vertical} is one of flights, stays, trains, or cars.

Idempotency

Every booking mutation and cost-calculation endpoint — create, confirm,
cancel, calculate-costs, and calculate-cancel-costs — requires a unique
Idempotency-Key request header. Reusing the same key for a retried request
returns the original result instead of performing the action twice; omitting the
header returns 422. Generate a fresh key (for example a UUID) per logical
operation and reuse it only when retrying that same operation.

Idempotency-Key: 018f2c3e-1234-7abc-8def-000000000001

Booking lifecycle

Create

POST /v1/{vertical}/bookings creates a booking from a built fareId. See the
per-vertical guides for the request body (flights,
stays, trains,
cars).

Calculate costs

POST /v1/{vertical}/bookings/calculate-costs returns the priced breakdown for
a fare before you commit — including any selected ancillaries, extras, seats,
and payment method.

{ "fareId": "018f...", "locale": "en_us", "isPersonal": false }

Confirm

POST /v1/{vertical}/bookings/{booking_id}/confirm confirms a pending booking.
The request body is optional.

Get and list

Retrieve a single booking:

GET /v1/{vertical}/bookings/{booking_id}

List bookings with offset pagination and filters (returns a JSON array):

GET /v1/bookings?vertical=flights&status=confirmed&limit=20&offset=0

Supported query parameters include vertical, status (repeatable),
tripId, sort (ASC/DESC by departure), departureDateFrom,
departureDateTo, limit, and offset. A booking's status is one of
pending, confirming, confirmed, issued, cancelled, failed, or
voided.

Cancel

Preview the refund first:

POST /v1/{vertical}/bookings/{booking_id}/calculate-cancel-costs

Then cancel, echoing the amount you expect to be charged/refunded so the server
can guard against a stale quote:

{ "estimatedTotalAmount": "149.90" }
POST /v1/{vertical}/bookings/{booking_id}/cancel

Trips

A trip groups related bookings (for example an outbound flight, a stay, and
a return flight) into one itinerary the traveler can browse.

Create

POST /v1/trips — supply either purpose (to name a fresh trip) or
bookingId (to seed the trip from an existing booking, deriving the name from
its destination). At least one is required; startsAt / endsAt are optional.

{
  "purpose": "Rome client visit",
  "bookingId": "018f...",
  "startsAt": "2026-02-10T08:00:00Z",
  "endsAt": "2026-02-14T20:00:00Z"
}

The response (TripOut) includes the trip id, status (one of planning,
booked, active, disrupted, completed, cancelled), and its segments.

List, get, and rename

GET   /v1/trips
GET   /v1/trips/{trip_id}
PATCH /v1/trips/{trip_id}

GET /v1/trips streams the traveler's trips as Server-Sent Events by default —
one event: trip frame per trip (each data: payload is a TripOut), closing
with event: done. Consume it like the
notification stream. In environments where
streaming is disabled it instead returns a plain JSON array of TripOut, so
branch on the response Content-Type (text/event-stream vs
application/json) and parse accordingly. GET /v1/trips/{trip_id} always
returns a single TripOut as JSON.

Associate and detach bookings

Attach an existing booking to a trip (atomically moving it from any current
trip):

POST /v1/trips/{trip_id}/bookings
{ "bookingId": "018f..." }

Detach a booking (the booking row is preserved; only the trip link is removed —
idempotent, returns 204):

DELETE /v1/trips/{trip_id}/bookings/{booking_id}

Timeline

GET /v1/trips/{trip_id}/timeline returns the ordered sequence of trip events
for rendering an itinerary view.

Real-time disruptions

When live-status coverage is available for a carrier, these endpoints surface
delays, cancellations, gate/platform changes, and equipment swaps:

GET /v1/trips/{trip_id}/disruptions
GET /v1/trips/{trip_id}/segments/{segment_id}/disruptions
GET /v1/trips/{trip_id}/segments/{segment_id}/realtime

Live-status coverage varies by carrier and region. Absence of a disruption
does not guarantee an on-time departure — treat these as best-effort signals.

For real-time push of new disruption alerts, see the
notification stream.

See the API Reference for the complete request and
response schemas.

Reporting issues

This page is maintained by the BizAway integration team. To request changes or
report an error, contact your BizAway integration contact. Edits made directly
in the ReadMe dashboard are overwritten on the next publish.