Handle changes and cancellations
Handle journey changes and cancellations that Transferz sends you.
You will keep your planning correct when a journey you drive is changed, cancelled or taken away from you. You need a webhook endpoint (see Receive journeys by webhook) and an API key.
Partners can change and cancel journeys after booking, and Transferz can move a journey to another company. You do not call anything to make this happen; you receive events and react to them.
| Event | Means | What you do |
|---|---|---|
journeyExecutionDetailsUpdatedEvent | The pickup time, pickup location or drop-off location changed. | Re-plan; tell the driver. |
journeyTravellerInfoUpdatedEvent | Traveller details changed: name, phone, passengers, luggage, flight, sign text or comments. | Update the details; tell the driver. |
journeyStatusChangedEvent with a cancelled status | The journey was cancelled. | Stop; free the driver and the vehicle. |
journeyFleetUnassignedEvent | The journey is no longer yours. | Remove it; stop sending updates. |
offerCreatedEvent with replacement true | A journey you accepted changed and is offered to you again (offer flow). | Accept or decline it. |
Step 1: Receive the change
When the partner moves the pickup from 14:30 to 15:15, you receive:
{ "journeyExecutionDetailsUpdatedEvent": { "created": "2026-11-28T16:20:03.517", "journeyId": 488213, "pickupTime": { "localTime": "2026-12-01T15:15:00", "timeZone": null }, "pickup": null, "dropoff": null }}Only the parts that changed have a value; the others are null. In this event the location keys are
pickup and dropoff, in lower case.
When traveller details change, you receive the fields that changed:
{ "journeyTravellerInfoUpdatedEvent": { "created": "2026-11-27T08:41:19.109", "journeyId": 488213, "adultPassengerCount": 3, "phone": "+447700900321", "firstName": null, "lastName": null, "flightNumber": null }}The examples are shortened. Acknowledge each event with 2xx before you process it.
Step 2: Fetch the current journey
Do not rebuild the journey from the event. Fetch it, and replace what you have:
/journeys/488213Referencecurl --request GET \ --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213' \ --header 'Accept: application/json' \ --header 'X-API-Key: YOUR_STAGING_API_KEY'{ "id": 488213, "code": "TZ7K4Q-1", "pickupTime": { "localTime": "2026-12-01T15:15:00", "timeZone": "Europe/Amsterdam" }, "status": "PLANNED", "assignmentStatus": "ASSIGNED", "travellerInfo": { "firstName": "Alex", "lastName": "Traveller", "phone": "+447700900321", "passengerCount": 3, "adultPassengerCount": 3 }, "hash": "9d1e4c7b2a0f8e6d5c4b3a2918f7e6d5c4b3a291807f6e5d4c3b2a1908f7e6d5"}Some changes have no event of their own, such as an added add-on. The journey's hash changes
whenever a detail that matters for planning changes, so compare it in your regular sync; see
Look up and search journeys.
Step 3: Tell the driver
Check that the assigned driver and vehicle still fit: the new pickup time, more passengers or more luggage may need another driver or a larger car. Change them as described in Assign a driver and a vehicle.
Cancellations
A cancelled journey arrives as a status change:
{ "journeyStatusChangedEvent": { "created": "2026-11-29T11:05:44.208", "journeyId": 488213, "previousStatus": "PLANNED", "newStatus": "CANCELLED_WITH_COSTS" }}The status tells you whether you are paid for it:
| Status | For you |
|---|---|
CANCELLED_WITH_COSTS | You are paid for the journey. |
CANCELLED_FREE | You are not paid for it. |
The partner can receive a different cancelled status for the same journey, because their charge is decided separately. Get a journey returns the status that applies to you.
A journey can be cancelled until the driver has arrived; once it is JOURNEY_IN_PROGRESS it can no
longer be cancelled. Cancelled statuses are final. After a cancellation:
- make sure your driver knows, and free the driver and the vehicle in your planning;
- stop sending positions and status updates;
- do not unassign the driver or the vehicle: changes to a cancelled journey are refused.
Journeys taken away from you
When Transferz moves a journey to another company, or a replacement offer is declined, you receive:
{ "journeyFleetUnassignedEvent": { "created": "2026-11-25T09:12:40.006", "journeyId": 488213, "transferCompanyId": 2290 }}Remove the journey from your planning, make sure the driver knows, and send no further updates for
it. If you fetch it later, assignmentStatus is REASSIGNED or the call is refused with 403.
Replacement offers
If you work with the offer flow, a change to a journey you accepted can come as a replacement offer
instead: an offerCreatedEvent with replacement set to true for a
journey you already have. Accept it to keep the journey with its new details; decline it and the
journey is taken away from you. See
Accept or decline offers.
Errors
| Problem | Cause | What to do |
|---|---|---|
403 when you fetch a changed journey | The journey was unassigned from you in the meantime. | Check for a journeyFleetUnassignedEvent; remove the journey. |
400 UNKNOWN ("already in a final state") when you change the driver | The journey was cancelled or completed. | Fetch the journey and stop working on it. |
| Change events arrive out of order with your own updates | Events for a journey wait for earlier failed ones. | Always fetch the journey and use its current state; compare created times. |
| A change is missed | The event was given up after its last attempt. | Run a regular sync with updatedAfter; see Look up and search journeys. |
Related
Endpoints