Skip to content

Cancel a journey or a booking

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

Updated · 3 min read

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 and read cancellationDetails:

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

Step 2: Cancel the journey

Call Cancel journey with a reason (required) from the 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:

POST/journeys/488213/cancelReference
Sign in to fill in your staging key. Sign in
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}'
Response 200
{  "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:

SituationacceptChargesResult
Free cancellation appliesfalse or trueCANCELLED_FREE; you are not charged
Free cancellation has passedtrueCANCELLED_WITH_COSTS
Free cancellation has passedfalseRefused with 400; the journey is unchanged

You also receive a journeyStatusChangedEvent 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 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.

POST/bookings/312840/cancelReference
Sign in to fill in your staging key. Sign in
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}'
Response 200
{  "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 to see which journeys are still active, then cancel those with acceptCharges true or one by one.

Errors

ProblemCauseWhat to do
400 with CANCELLATION_NOT_ALLOWED_FOR_JOURNEYFree 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 reasonThe reason is missing or not one of the listed values.Send a value from the cancellation reasons.
403 with INSUFFICIENT_PERMISSIONSThe journey or booking belongs to another partner.Check the id and the API key.
404No journey or booking with this id in this environment.Check the id and the environment.

Next steps

Was this helpful?