Skip to content

Handle changes and cancellations

Handle journey changes and cancellations that Transferz sends you.

Updated · 3 min read

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.

EventMeansWhat you do
journeyExecutionDetailsUpdatedEventThe pickup time, pickup location or drop-off location changed.Re-plan; tell the driver.
journeyTravellerInfoUpdatedEventTraveller details changed: name, phone, passengers, luggage, flight, sign text or comments.Update the details; tell the driver.
journeyStatusChangedEvent with a cancelled statusThe journey was cancelled.Stop; free the driver and the vehicle.
journeyFleetUnassignedEventThe journey is no longer yours.Remove it; stop sending updates.
offerCreatedEvent with replacement trueA 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:

JSON
{  "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:

JSON
{  "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:

GET/journeys/488213Reference
Sign in to fill in your staging key. Sign in
curl --request GET \  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213' \  --header 'Accept: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY'
Response 200
{  "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:

JSON
{  "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:

StatusFor you
CANCELLED_WITH_COSTSYou are paid for the journey.
CANCELLED_FREEYou 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:

JSON
{  "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

ProblemCauseWhat to do
403 when you fetch a changed journeyThe 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 driverThe journey was cancelled or completed.Fetch the journey and stop working on it.
Change events arrive out of order with your own updatesEvents for a journey wait for earlier failed ones.Always fetch the journey and use its current state; compare created times.
A change is missedThe event was given up after its last attempt.Run a regular sync with updatedAfter; see Look up and search journeys.

Was this helpful?