Booking lifecycle

Overview

Every shipment in Transdirect starts as a quote and progresses through a series of statuses as it moves from pricing to pickup to delivery.

Quotes and bookings are the same record

A “quote” and a “booking” are the same underlying record, differentiated only by status. When you call POST /api/bookings/v4, a record is created with status new — that’s the quote. Once you add details and confirm, the same record’s status progresses through pending_payment, paid, confirmed, etc. — and the same id is used throughout.

You don’t create a separate booking after quoting. You update the existing quote with full details, then confirm it.

flowchart LR
    A[Quote created] --> B[Details added]
    B --> C[Courier selected]
    C --> D[Payment]
    D --> E[Confirmed]
    E --> F[Picked up]
    F --> G[Delivered]

Booking statuses

Statuses are stored as machine codes. GET responses for non-quote bookings often return the human label instead (e.g. "Confirmed"). The labels come from a fixed lookup table, not from mechanical title-casing — note On hold and Sending to Courier — so treat matching as case-insensitive, or accept both forms. See get a booking for the same map alongside the GET response.

Machine code	Typical label	Description
new	new (v4 quote) / New (v5)	Quote has been created with basic details (sender/receiver postcodes, items). Pricing has been returned.
pending_payment	Pending Payment	Sender and receiver details have been added, a courier has been selected. Awaiting payment.
paid	Paid	Payment has been processed. The booking is ready to be sent to the courier.
pending_review	Pending Review	Flagged for manual review.
under_review	Under Review	Undergoing manual review.
request_sent	Request Sent	Submitted to the courier for confirmation.
request_failed	Request Failed	The courier was unable to process the booking. Contact support.
reviewed	Reviewed	Passed manual review and is being processed.
sending_to_courier	Sending to Courier	Actively being sent to the courier.
confirmed	Confirmed	The courier has confirmed the booking. A connote has been generated.
cancelled	Cancelled	Cancelled.
cancelled_refund	Cancel Refund	Cancelled with a refund.
booked_manually	Booked Manually	Processed manually by the Transdirect team.
on_hold	On hold	On hold.
on_hold_suspicious	Pending Review	On hold for fraud review. The label is the same as pending_review, so the label alone does not identify the code.
from_on_hold	from_on_hold	Released from an on-hold state. Deliberately unlabelled — the lookup table has no entry, so the raw code is returned as-is.
labels_failed	Labels Failed	Label generation failed.
demo	Demo	Legacy sandbox status. Bookings made with payment_method: "demo" do not get this status — they follow the normal lifecycle.
multipickup_unpaid	Multipickup Unpaid	Multipickup booking awaiting payment.

Step by step

1. Create a quote

Send a POST request to /api/bookings/v4 with the minimum required fields: sender and receiver postcodes/suburbs, and at least one item with weight and dimensions (in centimetres).

The response includes an id and quotes from all available couriers, keyed by courier string_id (e.g. allied, tnt_road_express).

2. Add sender and receiver details

Update the booking with PUT /api/bookings/v4/{id} to add full sender and receiver information: name, address, email, phone, and address type (business or residential).

3. Select a courier and pay

Choose a courier from the returned quotes and confirm with POST /api/bookings/v4/{id}/confirm, specifying:

• courier — the exact string_id from the quotes object
• pickup-date — hyphenated on v4 (YYYY-MM-DD)
• optional payment_method / payment — see how payments work

For API integrations, the cost is billed to your Transdirect credit account when you omit payment on confirm, or you can charge a saved payment method. API access is open by default; a live booking only requires the ability to pay. If you have neither a credit account nor a nominated saved payment method, the confirm is refused with 403 — use payment_method: "demo" to test without paying.

4. Get your label

Once confirmed, retrieve the shipping label with GET /api/bookings/v4/{id}/label. The label is returned as a PDF. A6 labels and manifests are also available on the same booking (/a6label, /manifest).

5. Track the shipment

Track the booking with GET /api/bookings/v4/track/{id}. See tracking for details on the response shape.

Important notes

Note

After a booking has been paid, changes can no longer be made. You can cancel the booking if it has not yet been confirmed by the courier. If the courier has already confirmed the booking, contact support@transdirect.com.au for assistance.

Note

To test without paying or shipping, set payment_method: "demo" when creating a booking. Demo bookings incur no charge and are never sent to couriers, but they follow the normal status lifecycle — a confirmed one lands on paid (returned as Paid), not on a demo status.