Cancel a journey or a booking
Cancel one journey or a whole booking, with or without cancellation charges.
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:
/journeys/488213Referencecurl --request GET \ --url 'https://warpdrive.staging.transferz.com/partners/journeys/488213' \ --header 'Accept: application/json' \ --header 'X-API-Key: YOUR_STAGING_API_KEY'{ "id": 488213, "code": "TZ7K4QM-1", "status": "CONFIRMED", "cancellationDetails": { "cancellable": true, "freeCancellationUntil": "2026-11-30T14:30:00", "freeCancellationWindowHours": 24 }}cancellableistruewhile the journey can still be cancelled: fromNOT_PAIDup to and includingDRIVER_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_APPROVALorPENDING, or beforefreeCancellationUntil. After that it is with costs: you are charged, and you must say so explicitly withacceptCharges.
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:
/journeys/488213/cancelReferencecurl --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}'{ "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 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.
/bookings/312840/cancelReferencecurl --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}'{ "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
| Problem | Cause | What to do |
|---|---|---|
400 with 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. |
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 to receive the status change by webhook.
- How a booking works for the full lifecycle.
Related
Walk-through