Create booking / Get quote

Endpoint

POST /api/bookings/v4

Creates a new booking and returns quotes from all available couriers. The booking is created with a new status and can be confirmed later with a selected courier and pickup date.

This endpoint serves as both a quote request and the first step in the booking lifecycle.

Note

A “quote” and a “booking” are the same record. This endpoint creates one record with status new. You then update it with full address details and confirm it — the same id is used throughout. There is no separate “convert quote to booking” step.

Authentication

Note

Requires authentication via API key or basic auth.

Request body

Top-level fields

Field	Type	Required	Description
declared_value	string	No	Declared value of the goods in AUD (e.g. "1000.00"). Used for insurance calculations. See warranty and insurance.
include_warranty	boolean	No	Set to false to opt out of warranty/insurance on this quote. Defaults to true. See warranty and insurance.
referrer	string	No	Identifies the source of the booking (e.g. "API", "WooCommerce").
requesting_site	string	No	URL of the site making the request (e.g. "http://www.example.com").
tailgate_pickup	boolean	No	Whether a tailgate (tail lift) is required at pickup. Defaults to false.
tailgate_delivery	boolean	No	Whether a tailgate (tail lift) is required at delivery. Defaults to false.
items	array	Yes	Array of item objects. At least one item is required.
sender	object	Yes	Sender location details.
receiver	object	Yes	Receiver location details.

Sender / Receiver object

The minimum fields required at quote time are postcode, suburb, type, and country. You can include the full address fields below at create time, or add them later via update booking before confirming.

Field	Type	Required	Description
postcode	string	Yes	Postcode of the location (e.g. "2000").
suburb	string	Yes	Suburb name in uppercase (e.g. "SYDNEY"). Can be auto-derived from postcode if omitted.
type	string	Yes	Address type: "business" or "residential".
country	string	No	ISO 3166-1 alpha-2 country code. Defaults to "AU". Use "US", "SG", etc. for international shipments.
state	string	No	State or territory abbreviation (e.g. "NSW", "VIC"). Auto-derived from postcode if omitted.
name	string	No	Contact name.
company_name	string	No	Company or business name.
email	string	No	Contact email address.
phone	string	No	Contact phone number.
address	string	No	Street address.

Note

Any other keys passed in the sender/receiver objects are silently ignored.

Item object

Field	Type	Required	Description
weight	string	Yes	Weight in kilograms (e.g. "5").
height	string	Yes	Height in centimetres (e.g. "25").
width	string	Yes	Width in centimetres (e.g. "35").
length	string	Yes	Length in centimetres (e.g. "40").
quantity	integer	Yes	Number of identical items.
description	string	Yes	Packaging type (e.g. "carton", "satchel", "pallet"). See items and packaging.
sku	string	No	Optional SKU. Echoed in the create response only — not persisted. Subsequent GET /bookings/v4/{id} calls will not return it. Useful when consumers want to correlate input items with the response item order.

Caution

Items exceeding 25kg must be on a forklift-able skid, pallet, or crate. If no forklift is available at pickup or delivery, set tailgate_pickup or tailgate_delivery to true. Additional surcharges apply.

Example request

curl -X POST \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "declared_value": "1000.00",
    "referrer": "API",
    "requesting_site": "http://www.example.com",
    "tailgate_pickup": false,
    "tailgate_delivery": false,
    "items": [
      {
        "weight": "5",
        "height": "25",
        "width": "35",
        "length": "40",
        "quantity": 1,
        "description": "carton"
      }
    ],
    "sender": {
      "postcode": "2000",
      "suburb": "SYDNEY",
      "type": "business",
      "country": "AU"
    },
    "receiver": {
      "postcode": "3000",
      "suburb": "MELBOURNE",
      "type": "business",
      "country": "AU"
    }
  }' \
  https://www.transdirect.com.au/api/bookings/v4

Example response

{
  "id": 12345678,
  "status": "new",
  "items": [
    {
      "weight": 5,
      "height": 25,
      "width": 35,
      "length": 40,
      "quantity": 1,
      "description": "carton"
    }
  ],
  "sender": {
    "postcode": "2000",
    "suburb": "SYDNEY",
    "type": "business",
    "country": "AU"
  },
  "receiver": {
    "postcode": "3000",
    "suburb": "MELBOURNE",
    "type": "business",
    "country": "AU"
  },
  "quotes": {
    "allied": {
      "total": 79.24,
      "price_insurance_ex": 72.09,
      "fee": 7.15,
      "insured_amount": 4500,
      "service": "road",
      "transit_time": "1-2 days",
      "pickup_dates": ["2025-08-27", "2025-08-28"],
      "pickup_time": {
        "from": "14:00",
        "to": "18:00"
      }
    },
    "couriers_please": {
      "total": 11.03,
      "price_insurance_ex": 10.03,
      "fee": 1.00,
      "insured_amount": 1000,
      "service": "road",
      "transit_time": "2-4 days",
      "pickup_dates": ["2025-08-27", "2025-08-28", "2025-08-29"],
      "pickup_time": {
        "from": "08:00",
        "to": "18:00"
      }
    },
    "tnt": {
      "total": 45.67,
      "price_insurance_ex": 41.52,
      "fee": 4.15,
      "insured_amount": 3000,
      "service": "road",
      "transit_time": "1-3 days",
      "pickup_dates": ["2025-08-27", "2025-08-28"],
      "pickup_time": {
        "from": "09:00",
        "to": "17:00"
      }
    }
  }
}

Quote response fields

Each courier quote object contains:

Field	Type	Description
total	number	Final price including warranty fee (AUD, GST-inclusive).
price_insurance_ex	number	Carrier price excluding the warranty/insurance fee (AUD, GST-inclusive).
fee	number	Warranty fee component (AUD). See warranty and insurance.
applied_gst	number	GST component of price_insurance_ex, calculated as price_insurance_ex / 11 rounded to 2 decimals. GST is computed on the carrier price only, not on the warranty fee.
insured_amount	number	Insured value (AUD). Equal to declared_value unless capped by the courier’s maximum — see warranty and insurance.
service	string	Service type (e.g. "road", "air").
transit_time	string	Estimated delivery timeframe (e.g. "1 Business Day", "2-5 Business Days").
pickup_dates	array	Available pickup dates in YYYY-MM-DD format.
pickup_time	object	Pickup time window with from and to fields in HH:MM format.
rate_card_code	string	Internal rate-card identifier (may be empty). Useful when raising support questions about pricing.
tiers	array	Optional. Frequent-rate (multipickup) pricing tiers, returned for Aramex and Couriers Please when frequent rates apply. See frequent rates for shape.

In addition to the keyed quotes object, the response includes a top-level quote_errors array listing couriers that could not provide a quote (e.g. [{"courier": "direct_couriers_express", "code": "no_service"}, ...]).

Warranty and insurance

Every quote includes warranty/insurance coverage based on declared_value. The fee and coverage cap vary by courier.

How it works

Each courier sets its own rules:

• Some couriers include free coverage up to a per-courier cap. For these, fee is 0 and insured_amount is the lower of your declared_value and the cap.
• Other couriers charge a tiered warranty fee based on the declared_value bracket, up to a per-courier maximum coverage. If declared_value exceeds the cap, insured_amount is returned at the capped value (not your declared value).

The exact fees and caps differ by courier and may change over time. Treat the values returned in fee, insured_amount, and total as authoritative — do not hardcode warranty pricing in your integration.

Opting out of warranty

Send include_warranty: false in the request body to receive quotes without warranty. Every courier in the response will return fee: 0 and insured_amount: 0.

include_warranty: false takes precedence over declared_value — even if you send a non-zero declared_value, no warranty will be added when include_warranty is false. It also bypasses any API-key-level auto-insurance setting that would otherwise top up a zero declared value.

Implications

• fee and insured_amount are courier-specific. Read them from each quote object — don’t assume parity across carriers.
• Compare total, not price_insurance_ex. Two carriers with the same headline price will have different totals once warranty is included.
• GST is on price_insurance_ex only. applied_gst = round(price_insurance_ex / 11, 2). The warranty fee is not GST-bearing in the quote response.
• After confirmation, the booking response replaces quotes with cost and insured_value reflecting the selected courier’s coverage.

Tip

Compare the total field across couriers to find the cheapest option, or use transit_time to find the fastest. The quote response includes all available couriers for the given route.

International bookings

For international shipments, set the country field on the sender or receiver to the appropriate ISO 3166-1 alpha-2 code (e.g. "US", "SG", "NZ"). If omitted, the country defaults to "AU".

International bookings may require a customs declaration before the booking can be confirmed.

Next steps

• Update the booking with full sender and receiver details
• Confirm the booking with a selected courier
• Learn about frequent rates for discounted pricing