The object model

Before you write your first integration call, it helps to know what each
object on the /v1 surface represents and which ID you carry from one call
to the next. This page names every object you will meet across search,
fares, and bookings, then walks through the two state machines that
determine what you can do at each step: the booking lifecycle, and the fare
lifecycle that leads up to it.

Examples on this page use the same company and traveler as the rest of these
guides: Acme Travel Ltd (consumer slug acme-travel), traveler Ada
Lovelace ([email protected]), and a Milan–London trip.

What this covers

Every object you handle between a search and a confirmed booking:
Traveler, consumer traveler, Account, Solution, Fare, built fare, Booking,
Trip, and Segment.
The difference between a Traveler and a consumer traveler, and why it
decides which credential you send.
How a booking moves through its lifecycle, with every state the booking
status enum defines.
How a fare moves from a search result to a built, bookable fare, including
how long you have before it expires.

How it works

The objects

Traveler — the person the trip is for. A Traveler signs in themselves and
presents a bearer token on every request; travel.tech resolves their identity
from that token with
get the signed-in traveler's identity. Ada
Lovelace, above, is a Traveler: her identity record carries her own id
(018f2c1a-9b3e-7c4d-8a1f-3e5b7c9d1a2f) and the Account she belongs to.

Consumer traveler — a traveler record your integration provisions
directly for someone who never signs in to travel.tech at all. If your
consumer registration is bound to an account, you create, list, update, and
look up these records yourself under
/v1/consumer/travelers using only
your consumer credential. The record reports whether it has since become a
full, sign-in-capable Traveler (isRegistered); until then, no bearer token
exists for it. Use a consumer traveler when
your own product owns the end-user relationship and you only need
travel.tech to hold a travel profile for them; use a Traveler when the
person signs in and acts on their own behalf.

Account — the organization a Traveler belongs to. You don't fetch an
Account as its own resource; it's surfaced as the accountId and
accountName fields on the Traveler's identity, and it's what scopes policy
and approval rules to that organization.

Solution — one bookable option a search returns: one flight itinerary,
one room at one property, one train, one car. Each solution carries a
solutionKey that correlates it to the fares and the eventual booking.
Search streams solutions over Server-Sent Events; see the per-vertical
guides (for example searching stays) for the request
shape.

Fare — one priced way to buy a solution. A single solution can offer
several fares — different cabin classes, fare families, or refund
conditions — and the fare is what the traveler ultimately pays for. Listing
fares (for example
search_stay_fares) returns a fareId for
each option, but that fareId is not yet locked: the price and
availability can still move before you build it.

Built fare — the same fare, locked. Calling the vertical's build-fare
operation (for example
build_stay_fare) re-checks the fare with the
provider and, if it's still available, locks its price and returns a
fareId you can pass straight to booking creation. A fare you only listed
cannot be booked — it has to be built first. See
Fare lifecycle below for how long a built fare stays
valid.

Booking — a purchase of one vertical's inventory, created from a built
fare with create_booking. A booking's own
identifier is its bookingId, and it moves through the lifecycle described
in Booking lifecycle below.

Trip — a container that groups a traveler's bookings across verticals
under one name and date range — for example, Ada's Milan trip
(018f2c1d-2b3c-7d4e-8f5a-6b7c8d9e0f1a) might hold her outbound flight, her
stay, and her return flight together. Create one with
create_trip and read it back with
get_trip; pass its tripId when you create a
booking to attach the booking to it.

Segment — a stage within a trip: a destination and date window that
groups the bookings for that part of the journey (for example, "the London
leg"). Segments are returned inline on the trip object from get_trip —
there's no separate segment endpoint — and each one lists the bookings that
play an ingress, stay, car, or egress role within it. See
Managing bookings and trips for how segments are
built from the bookings you attach.

IDs worth keeping

Keep these three IDs as you move through a flow: the solution's
solutionKey (to fetch fares for it), the fare's fareId (to build it,
then to book it), and the resulting booking's bookingId (to confirm,
cancel, or attach it to a trip). A tripId is optional and only needed once
you want to group bookings together.

Booking lifecycle

A booking's status is one of eight values. Only pending, confirming,
confirmed, and issued can still change; cancelled, failed, voided,
and rejected are end states.

From	Can move to
`pending`	`confirming`, `confirmed`, `cancelled`, `failed`, `rejected`
`confirming`	`confirmed`, `cancelled`, `failed`, `voided`
`confirmed`	`issued`, `cancelled`, `voided`
`issued`	`cancelled`, `voided`

pending — the booking was created and is waiting on confirmation (or,
if it needs supervisor review first, on that
decision).
confirming — travel.tech has submitted the booking to the provider and
is waiting for a final ticketing result. You can still cancel from here.
confirmed — the provider has accepted the booking. For stays, cars,
and trains this is already the terminal success state.
issued — ticketing has completed. Flights move on to this state after
confirmed; the other verticals have no separate ticketing step, so they
never reach issued.
rejected — the booking request was deliberately declined, most
commonly by supervisor review, before it reached
the provider. This is distinct from failed: a rejection is a decision,
not an error.
cancelled — you or the provider cancelled the booking.
failed — the booking could not be completed because of an error
(payment, provider, or validation failure).
voided — the provider reversed a booking it had already confirmed,
including one that was still being ticketed.

Read the current status from the booking detail response — see
Managing bookings and trips.

Fare lifecycle

A fare moves through up to four stages before it becomes a booking:

solution → fare (listed) → built fare (locked) → booking

A solution comes back from search.
Listing fares for that solution returns one or more fares, each with
a fareId and a price that is not yet guaranteed.
Building a fare locks it: the built fare carries a fareId — some
verticals keep the id you listed, others mint a new one when they
lock it — and a price the provider will honor for a limited time. Always
use the fareId the build step returns, not the one you listed.
Creating a booking from that fareId finishes the flow.

How long you have. Once you build a fare for flights, stays, or cars, its
fareId stays valid for booking for 30 minutes. For trains, the hold
lasts however long the train provider declares for that fare — this varies
a lot by supplier, from well under an hour to several days — falling back
to the same 30-minute default when no usable deadline is supplied, and
never exceeding 30 days regardless of what the provider declares.

What happens when it expires. Calling the build-fare operation (or
creating a booking) with an expired or unknown fareId returns 410 with
the standard error envelope:

{
  "error": {
    "code": "OFFER_EXPIRED",
    "message": "This fare is no longer available. Search again to get a current price.",
    "details": [],
    "recoveryAction": "CHANGE_SELECTION",
    "retryAfterSeconds": null
  }
}

The only way forward is to search again. If your fare lapsed after a
traveler already signed in and locked it once, you can re-lock the same
offer instead of restarting the whole search — each vertical has its own
re-quote operation, for example
requote_stay_fare.

What you need to handle

Build before you book. A fareId you only listed (never built)
cannot be passed to booking creation.
The 30-minute (or provider-declared, for trains) clock starts at
build, not at search. Don't cache a built fare's fareId and expect it
to still be valid later — build it right before you book.
OFFER_EXPIRED means search again, not retry the same call. Your
retry logic should treat 410 as non-retryable and start over from
search, or use re-quote if the traveler already has a signed-in session.
rejected is a deliberate decline, not an error. Don't treat it the
same as failed in your error handling — there's nothing to retry.
Choose the right identity. Use a Traveler (bearer token) for anyone
who signs in and acts for themselves; use a consumer traveler record when
your own product manages the person and travel.tech only needs a profile
to book against.

Related guides

Authentication — the consumer HMAC and traveler
bearer token this page's identities depend on.
Managing bookings and trips — the full booking
lifecycle in practice, plus trips and segments.
Searching and booking stays — a complete search-to-book
walkthrough for one vertical.
Approvals — how supervisor review fits into the
booking lifecycle.
Errors — the full error
envelope and recovery-action vocabulary.
Guest checkout — booking without a signed-in
Traveler at all.