Booking lifecycle

A Transdirect booking is one record from the first quote to delivery. It keeps the same id throughout, and its status_code tells you where it is.

From quote to delivery

1. Quote. POST /api/v5/quotes returns prices from every courier you can use and creates a draft booking with status_code: "new". Keep the id.

2. Add details. PATCH /api/v5/bookings/{id} adds what the quote did not need: names, street addresses, phones, emails and the goods description.

3. Confirm. POST /api/v5/bookings/{id}/confirm with the chosen quote’s courier key, a pickup date from that quote’s pickup_dates, an optional pickup time, and a payment_method. Transdirect charges the payment method and returns 204. See payments.

4. Lodgement. The booking becomes paid, then Transdirect sends it to the courier. When the courier accepts the job the booking moves to confirmed and carries the courier’s connote. Some bookings are held for a check first (see bookings held for review).

5. Label. Once the booking is ready for its courier, download the label and attach it to the parcel.

6. Tracking. After pickup, track the shipment until it is delivered.

Transdirect does not send webhooks. Poll get a booking after confirming, or poll list bookings with If-None-Match to watch many bookings cheaply.

What you can change, and when

Stage	status_code	You can
Draft	new	Update details and items, confirm, or delete the draft. Drafts are never charged and do not appear in the booking list.
Paid and later	paid onwards	Read the booking and download documents. Booking updates and deletes are refused. Use cancel for eligible account-credit or demo bookings.
Cancelled	cancelled, cancelled_refund	Read only.

To cancel an eligible account-credit or demo booking, send POST /api/v5/bookings/{id}/cancel with a required reason. It returns cancelled: true when cancellation completes, or cancelled: false when the request is submitted to support. Demo bookings have nothing to refund. Card and PayPal bookings return 422; use the members area or contact support for those. See cancel a booking.

Prices are worked out again at confirm from the booking’s current details. If you change items or addresses after quoting, quote again to see the price you will be charged.

Booking statuses

Every booking response has two status fields:

• status_code is the machine code, for example confirmed. Switch on this.
• status is a display label, for example Confirmed. Two codes share the label Pending Review, and one code has no label, so do not branch on it.

The quote response returns status: "new" in lower case; get a booking returns New. Treat any status_code you do not recognise as a new state rather than an error.

status_code	status	Meaning
new	New	Draft quote. Not confirmed, not charged.
pending_payment	Pending Payment	Payment has started but not finished.
paid	Paid	Paid. Waiting to be sent to the courier.
pending_review	Pending Review	Paid, and held for a Transdirect check before it is sent to the courier.
under_review	Under Review	Being looked at by the Transdirect team.
on_hold	On hold	Paid, and held by Transdirect before it is sent to the courier.
on_hold_suspicious	Pending Review	Paid, and held for an account security check.
from_on_hold	from_on_hold	Released from a hold. Returned with no label.
reviewed	Reviewed	Released after review. Waiting to be sent to the courier.
sending_to_courier	Sending to Courier	Being lodged with the courier now.
request_sent	Request Sent	Lodged. Waiting for the courier to accept the job.
confirmed	Confirmed	Accepted by the courier. The connote is set.
request_failed	Request Failed	The courier did not accept the request. Transdirect follows it up.
labels_failed	Labels Failed	Lodged, but the label could not be produced. Transdirect reprints it.
booked_manually	Booked Manually	Booked with the courier by the Transdirect team.
multipickup_unpaid	Multipickup Unpaid	A multi-pickup booking awaiting payment.
cancelled	Cancelled	Cancelled.
cancelled_refund	Cancel Refund	Cancelled and refunded.
demo	Demo	A Demo courier booking confirmed without a payment method. Demo bookings confirmed with payment_method: "demo" end at confirmed instead. See demo mode.

When the label is ready depends on the courier as well as the status. See when a label is ready.

Bookings held for review

Some bookings are checked by the Transdirect team after payment and before they go to the courier. A held booking shows pending_review, on_hold or on_hold_suspicious. It stays paid, and it has no label until it is released. When it is released it moves to reviewed (or back to paid) and is sent to the courier.

Reasons a booking can be held include:

• No goods description. Send goods_description (what is inside the parcels) when you quote or update.
• International services, such as TNT and FedEx international. A FedEx international document service is not held for this reason when you send fedex_document_type at confirm.
• Package types that need a check: Unpackaged or Other/Misc items, and skids, pallets or crates on TNT domestic services.
• Heavy items that are over the courier’s carton weight limit.
• A declared value of $20,000 or more.
• Courier-specific checks, for example some Northline consignments.
• Account checks that Transdirect runs on bookings.

Holds are part of normal operation. You do not need to do anything for a held booking unless Transdirect contacts you. If you want to know why one was held, contact Transdirect support with the booking id.

Related

• Quote and create a booking: the full sequence with requests and responses
• Payments
• Testing with demo mode
• Tracking shipments