# Handle changes and cancellations

> Handle journey changes and cancellations that Transferz sends you.

Section: Transfer companies · Last updated: 2026-11-15

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](https://developers.test.transferz.com/guides/transfer-companies/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`](https://developers.test.transferz.com/reference/webhooks/journey-details-updated)              | The pickup time, pickup location or drop-off location changed.                              | Re-plan; tell the driver.              |
| [`journeyTravellerInfoUpdatedEvent`](https://developers.test.transferz.com/reference/webhooks/traveller-details-updated)               | Traveller details changed: name, phone, passengers, luggage, flight, sign text or comments. | Update the details; tell the driver.   |
| [`journeyStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-status-changed) with a cancelled status | The journey was cancelled.                                                                  | Stop; free the driver and the vehicle. |
| [`journeyFleetUnassignedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-unassigned)                           | The journey is no longer yours.                                                             | Remove it; stop sending updates.       |
| [`offerCreatedEvent`](https://developers.test.transferz.com/reference/webhooks/offer-created) 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:

```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:

**Request:** [`GET /journeys/488213`](https://developers.test.transferz.com/reference/transfer-companies/get-journey)

```bash title="cURL"
curl --request GET \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213", {
  method: "GET",
  headers: {
    Accept: "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
});

const data = await response.json();
console.log(response.status, data);
```

```java title="Java"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}
```

```csharp title="C#"
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```php title="PHP"
<?php

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

echo $status, PHP_EOL, $response, PHP_EOL;
```

**Response (200):**

```json
{
  "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](https://developers.test.transferz.com/guides/transfer-companies/look-up-and-search-journeys#what-the-journey-fields-mean).

## 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](https://developers.test.transferz.com/guides/transfer-companies/assign-a-driver-and-vehicle#change-the-driver-or-the-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:

| 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](https://developers.test.transferz.com/reference/transfer-companies/get-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`](https://developers.test.transferz.com/reference/webhooks/offer-created) 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](https://developers.test.transferz.com/guides/transfer-companies/accept-or-decline-offers#replacement-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](https://developers.test.transferz.com/guides/transfer-companies/look-up-and-search-journeys#catch-up-after-missed-events). |

## Related

### Endpoints

- [GET Get journey](https://developers.test.transferz.com/reference/transfer-companies/get-journey) (`GET /journeys/{id}`)
- [GET Search journeys](https://developers.test.transferz.com/reference/transfer-companies/search-journeys) (`GET /journeys`)
