Cancel a booking

Endpoint

POST /api/v5/bookings/{id}/cancel

Cancels a paid booking and records the reason. When the booking can be cancelled automatically, it is cancelled and any account-credit refund is applied. When it cannot (for example the courier has already collected it), the same call submits the request to support instead of cancelling it in place.

An immediately cancelled booking stays on record with status cancelled or cancelled_refund. To remove an unpaid draft entirely, delete it.

Authentication

Note

Requires authentication via API key. The booking must belong to the authenticated member.

Path parameters

Parameter	Type	Required	Description
id	integer	Yes	The unique booking ID.

Request body

Send a JSON object with Content-Type: application/json. The reason is trimmed and must not be empty.

Field	Type	Required	Description
reason	string	Yes	Why the booking is being cancelled. A blank reason is refused.

Example request

curl -X POST \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer requested cancellation" }' \
  https://api.transdirect.com.au/api/v5/bookings/12345678/cancel

Response

A cancellation that completes immediately returns 200 with:

{ "success": true, "cancelled": true }

A request that had to be sent to support returns 200 with:

{
  "success": true,
  "cancelled": false,
  "message": "Cancellation request submitted to support"
}

cancelled: false means the booking is still active and support has the request. It is not a failure.

SDK example

import { client, postApiV5BookingsByIdCancel } from '@transdirect/api-sdk';

client.setConfig({ headers: { 'api-key': process.env.TD_API_KEY! } });

const { data, error, response } = await postApiV5BookingsByIdCancel({
  path: { id: '12345678' },
  body: { reason: 'Customer requested cancellation' },
});
if (response.status !== 200 || error) throw new Error(JSON.stringify(error));
console.log(data?.cancelled ? 'Cancelled' : 'Submitted to support');

Who can cancel through the API

Automatic cancellation and the account-credit refund are available for account-credit bookings, and for demo bookings that were never charged. A card or PayPal booking is refused with 422. Contact support@transdirect.com.au to cancel one of those.

The booking must be in paid, request_sent, confirmed, pending_review, under_review, reviewed or demo status. A quote (new or pending_payment) cannot be cancelled this way; delete removes an unpaid draft instead.

Error responses

Status code	Description
400	The reason is missing, the body is not a JSON object, or the booking is not in a cancellable state.
401	Unauthorised: invalid or missing API key.
404	No booking exists with the given ID, or it belongs to another member.
409	A cancellation for this booking is already in progress.
422	Only account-credit bookings can be cancelled through the API, or the refund was refused.
429	More than 600 requests a minute on this key. Wait for the retry-after seconds.
502	The booking could not be cancelled automatically and support could not be reached.

PHP business-rule errors use { "errors": ["..."] }. The Worker returns 401 with {"error":"missing_api_key"} or {"error":"invalid_api_key"}, and 404 with {"error":"booking_not_found"}. Invalid request bodies can instead return a Zod validation error with 400. Rate limiting returns 429 {"error":"rate_limited"} with a retry-after header.

Next steps

• Get the booking to confirm the updated status
• Delete a booking when the record is an unpaid draft you want removed