Trip Lifecycle System

Taxi & Private Hire › Products › Trip › Trip Lifecycle System

Generally available

An end-to-end view of how a trip moves through its states — from booking through allocation, dispatch and in-progress to finished or cancelled — and how a trip, its segments and their stops relate as it progresses, including merging and the pre-booking staging window. The individual lifecycle features cover each stage.

The states a trip moves through

Every trip is a small state machine. From booking it is released for dispatch, offered to or assigned a driver, started, and finished — or cancelled at any point along the way. The platform only ever permits the moves below; a request for any other transition is rejected outright (an invalid progression error), so an integration can't push a trip into a state it isn't allowed to be in.

The forward path runs Scheduled → In Allocation → Offered → Assigned → In Progress → Completed. Paused, the staging "pending confirmation" step and a reclaim back to allocation are side moves; Cancelled is reachable from any active state. Completed and Cancelled are terminal. (Recurring masters sit outside the flow — they only cancel.)

The guards on each move

Most transitions carry a guard — a precondition checked before the move is allowed. The important ones:

Ready for dispatch — a trip only enters In Allocation once it's complete enough to dispatch; reverting to Scheduled requires the opposite.
A driver is present and active — moving to Offered, Assigned, Pending confirmation or In Progress requires the relevant driver to exist and (for assignment) to be an active driver.
Passenger safety on reclaim — a trip can only be pulled back from a driver (In Progress → In Allocation/Paused) when there's no passenger on board.
Confirm only from staging — a self-service booking can only be confirmed while it's still in Pending confirmation.

A guard that fails blocks the move (a hard guard raises an error; a soft guard records a fatal failure and rolls back), so the trip never half-transitions.

Every legal transition

From each state, these are the only moves a trip can make — anything else is rejected. The guard, where shown, must hold for the move to be allowed.

From	Can move to
Scheduled	In Allocation — the trip is ready for dispatch Offered — a driver has been designated Assigned — a driver is assigned and active Pending confirmation — a driver is assigned and active Paused Scheduled (paused) Cancelled
Scheduled (paused)	Scheduled In Allocation — ready for dispatch Offered — a driver designated Assigned — driver assigned and active Pending confirmation — driver assigned and active Paused Cancelled
In Allocation	Offered — a driver designated Assigned — driver assigned and active Pending confirmation — driver assigned and active In Progress — a driver is assigned Scheduled — the trip is no longer ready for dispatch Paused Cancelled
Paused	In Allocation — resuming from a paused state Assigned — driver assigned and active In Progress — a driver is assigned Offered — a driver designated Scheduled Scheduled (paused) Cancelled
Offered	Assigned — driver assigned and active In Allocation Scheduled Scheduled (paused) Paused Cancelled
Pending confirmation	Assigned — the driver confirms (must still be staging) In Allocation — the driver rejects or times out Cancelled
Assigned	In Progress — a driver is assigned In Allocation Cancelled
In Progress	Completed — all stops resolved In Allocation — reclaim — no passenger on board Paused — reclaim — no passenger on board Cancelled
Recurring master	Cancelled
Completed · terminal	— no transitions (terminal state)
Cancelled · terminal	— no transitions (terminal state)

Each stage is detailed on its own page (allocation, offers, in-progress, cancellation); the guards above compose with the arrival and no-show guards on the stops within a trip.

Example request

POST /client/{clientId}/tripsegmentstop/{tripSegmentStopId}/arrived

See the API reference for the full request and response schema.

Endpoints

Method	Path
`POST`	`/client/{clientId}/tripsegmentstop/{tripSegmentStopId}/arrived` · primary
`POST`	`/client/{clientId}/tripsegmentstop/{tripSegmentStopId}/call-customer`
`POST`	`/client/{clientId}/tripsegmentstop/{tripSegmentStopId}/cancel`
`POST`	`/client/{clientId}/tripsegmentstop/{tripSegmentStopId}/finished`
`POST`	`/client/{clientId}/tripsegmentstop/{tripSegmentStopId}/noshow`

Full request/response schemas and an interactive explorer will live in the API reference (coming soon).

Use cases

Operator flows that exercise this feature.

Log a customer contact

action risk: low

Record an attempt to contact the customer at a stop (counts toward the no-show call guard).

POST /client/{clientId}/tripsegmentstop/{tripSegmentStopId}/call-customer

Mark a no-show