# Cancel a journey or a booking

> Cancel one journey or a whole booking, with or without cancellation charges.

Section: Partners · Last updated: 2026-11-15

You will cancel a journey, for example only the return leg, or every journey in a booking. You need
the journey `id` or the booking `id`, and a cancellation reason.

## Step 1: Check the cancellation terms

[Get journey](https://developers.test.transferz.com/reference/partners/get-journey) and read `cancellationDetails`:

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

```bash title="cURL"
curl --request GET \
  --url 'https://warpdrive.staging.transferz.com/partners/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/partners/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/partners/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/partners/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/partners/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": "TZ7K4QM-1",
  "status": "CONFIRMED",
  "cancellationDetails": {
    "cancellable": true,
    "freeCancellationUntil": "2026-11-30T14:30:00",
    "freeCancellationWindowHours": 24
  }
}
```

- `cancellable` is `true` while the journey can still be cancelled: from `NOT_PAID` up to and
  including `DRIVER_ARRIVED`. Once the traveller is on board (`JOURNEY_IN_PROGRESS`), or the journey
  is completed or already cancelled, it cannot be cancelled.
- The cancellation is **free** while the journey is `NOT_PAID`, `AWAITING_APPROVAL` or `PENDING`, or
  before `freeCancellationUntil`. After that it is **with costs**: you are
  charged, and you must say so explicitly with `acceptCharges`.

Tell the traveller which applies before you cancel.

> **To be confirmed by Transferz:** The default free-cancellation window is still to be confirmed by Transferz. Use the
> `freeCancellationUntil` value of each journey rather than a fixed number of hours.

## Step 2: Cancel the journey

Call [Cancel journey](https://developers.test.transferz.com/reference/partners/cancel-journey) with a `reason` (required) from the
[cancellation reasons](https://developers.test.transferz.com/guides/essentials/constants#cancellation-reasons). Set `acceptCharges` to
`true` only when the traveller has accepted the costs; it defaults to `false`.

This example cancels after the free window, accepting the costs:

**Request:** [`POST /journeys/488213/cancel`](https://developers.test.transferz.com/reference/partners/cancel-journey)

```bash title="cURL"
curl --request POST \
  --url 'https://warpdrive.staging.transferz.com/partners/journeys/488213/cancel' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "reason": "NOT_NEEDED_ANYMORE",
  "acceptCharges": true
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/partners/journeys/488213/cancel", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "reason": "NOT_NEEDED_ANYMORE",
    "acceptCharges": true
  }),
});

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 {
    String body = """
        {
          "reason": "NOT_NEEDED_ANYMORE",
          "acceptCharges": true
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/partners/journeys/488213/cancel"))
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("POST", HttpRequest.BodyPublishers.ofString(body))
        .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.Post, "https://warpdrive.staging.transferz.com/partners/journeys/488213/cancel");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

var json = """
    {
      "reason": "NOT_NEEDED_ANYMORE",
      "acceptCharges": true
    }
    """;
request.Content = new StringContent(json, Encoding.UTF8, "application/json");

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

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

$body = <<<'JSON'
{
  "reason": "NOT_NEEDED_ANYMORE",
  "acceptCharges": true
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/partners/journeys/488213/cancel');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$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": "TZ7K4QM-1",
  "status": "CANCELLED_WITH_COSTS",
  "cancellationDetails": {
    "cancellable": false,
    "freeCancellationUntil": "2026-11-30T14:30:00",
    "freeCancellationWindowHours": 24
  }
}
```

The response is the journey with its new status:

| Situation                    | `acceptCharges`   | Result                                       |
| ---------------------------- | ----------------- | -------------------------------------------- |
| Free cancellation applies    | `false` or `true` | `CANCELLED_FREE`; you are not charged        |
| Free cancellation has passed | `true`            | `CANCELLED_WITH_COSTS`                       |
| Free cancellation has passed | `false`           | Refused with `400`; the journey is unchanged |

You also receive a [`journeyStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-status-changed) with the new
status. A cancellation cannot be undone; book again if the traveller changes their mind.

## Step 3: Or cancel the whole booking

[Cancel booking](https://developers.test.transferz.com/reference/partners/cancel-booking) cancels every journey of the booking that can still be
cancelled, with one `reason` and one `acceptCharges` for all of them. Journeys that can no longer be
cancelled, such as completed ones, are left as they are. The response is the booking; check the
status of each journey in it.

**Request:** [`POST /bookings/312840/cancel`](https://developers.test.transferz.com/reference/partners/cancel-booking)

```bash title="cURL"
curl --request POST \
  --url 'https://warpdrive.staging.transferz.com/partners/bookings/312840/cancel' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "reason": "NOT_NEEDED_ANYMORE",
  "acceptCharges": false
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/partners/bookings/312840/cancel", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "reason": "NOT_NEEDED_ANYMORE",
    "acceptCharges": false
  }),
});

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 {
    String body = """
        {
          "reason": "NOT_NEEDED_ANYMORE",
          "acceptCharges": false
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/partners/bookings/312840/cancel"))
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("POST", HttpRequest.BodyPublishers.ofString(body))
        .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.Post, "https://warpdrive.staging.transferz.com/partners/bookings/312840/cancel");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

var json = """
    {
      "reason": "NOT_NEEDED_ANYMORE",
      "acceptCharges": false
    }
    """;
request.Content = new StringContent(json, Encoding.UTF8, "application/json");

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

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

$body = <<<'JSON'
{
  "reason": "NOT_NEEDED_ANYMORE",
  "acceptCharges": false
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/partners/bookings/312840/cancel');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$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": 312840,
  "code": "TZ7K4QM",
  "partnerReference": "ORDER-10023",
  "journeys": [
    { "id": 488213, "code": "TZ7K4QM-1", "status": "CANCELLED_FREE" },
    { "id": 488214, "code": "TZ7K4QM-2", "status": "CANCELLED_FREE" }
  ]
}
```

> **A refused booking cancellation can be partial:** The journeys are cancelled one by one. If one of them is past its free-cancellation time and
> `acceptCharges` is `false`, the call fails with `400`, but journeys cancelled before it stay
> cancelled. After an error, call [Get booking](https://developers.test.transferz.com/reference/partners/get-booking) to see which journeys
> are still active, then cancel those with `acceptCharges` `true` or one by one.

> **To be confirmed by Transferz:** How a cancelled journey is refunded or left off the invoice for each payment method is still to be
> confirmed by Transferz.

## Errors

| Problem                                                                                                                                        | Cause                                                                                                                       | What to do                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` with [CANCELLATION_NOT_ALLOWED_FOR_JOURNEY](https://developers.test.transferz.com/reference/errors/cancellation-not-allowed-for-journey) | Free cancellation has passed and `acceptCharges` is `false`, or the journey is in progress, completed or already cancelled. | Confirm the costs with the traveller and retry with `acceptCharges` `true`. A journey that is in progress or finished cannot be cancelled. |
| `400` with a `field` `reason`                                                                                                                  | The reason is missing or not one of the listed values.                                                                      | Send a value from the [cancellation reasons](https://developers.test.transferz.com/guides/essentials/constants#cancellation-reasons).      |
| `403` with `INSUFFICIENT_PERMISSIONS`                                                                                                          | The journey or booking belongs to another partner.                                                                          | Check the id and the API key.                                                                                                              |
| `404`                                                                                                                                          | No journey or booking with this id in this environment.                                                                     | Check the id and the environment.                                                                                                          |

## Next steps

- [Follow a journey](https://developers.test.transferz.com/guides/partners/follow-a-journey) to receive the status change by webhook.
- [How a booking works](https://developers.test.transferz.com/guides/partners/how-a-booking-works) for the full lifecycle.

## Related

### Endpoints

- [POST Cancel journey](https://developers.test.transferz.com/reference/partners/cancel-journey) (`POST /journeys/{journeyId}/cancel`)
- [POST Cancel booking](https://developers.test.transferz.com/reference/partners/cancel-booking) (`POST /bookings/{id}/cancel`)
- [GET Get journey by id](https://developers.test.transferz.com/reference/partners/get-journey) (`GET /journeys/{journeyId}`)

### Walk-through steps

- [Cancel](https://developers.test.transferz.com/walkthrough/partner/cancel)
