Update a booking

Change a draft booking before you confirm it. The usual use is adding the full sender and receiver details to the quote you created with postcodes and suburbs only. Confirm needs a name, email, phone and address for both, plus company_name for a business address.

PATCH /api/v5/bookings/{id}
PUT /api/v5/bookings/{id}

PUT and PATCH behave the same: only the fields you send change. Requires your API key in the api-key header.

Updates are accepted only until the booking is paid. Once it is confirmed and paid, the booking is locked.

Path parameters

Parameter	Type	Description
id	integer	The Transdirect booking id from your quote.

Request body

Send JSON with Content-Type: application/json. Every field is optional. Fields not listed here are rejected.

Field	Type	Description
sender	object	Sender (pickup) address fields to change. See address fields.
receiver	object	Receiver (delivery) address fields to change. See address fields.
goods_description	string	What is inside the parcels, for example Books. Up to 80 characters. description is accepted as an alias.
declared_value	number	Value of the goods in AUD, which sets the transit warranty cover. 0 means no cover.
insured_value	number	Optional, AUD, 0 or more. Stored on the booking.
items	array	Item lines to change or add. Include an item’s id to change it; leave id out to add a new line. See item fields.
tailgate_pickup	boolean	Request a tail-lift truck at pickup.
tailgate_delivery	boolean	Request a tail-lift truck at delivery.
instructions	object	{ "pickup": "...", "delivery": "..." } free-text driver instructions. See the note below.
customer_reference	string	Your own reference, such as an order number. Up to 80 characters. An empty string clears it.

Address fields

address, company_name, email, name, phone, postcode, suburb, state, country (two-letter ISO code, for example AU) and type (business or residential).

Item fields

id, description (the package type, for example Carton or Satchel; see items and packaging), weight (kg), length, width and height (cm), and quantity. A new line needs all six measurement and description fields. To remove a line, use delete a booking item.

Instructions set authority to leave

Sending instructions.delivery also records authority to leave at the front door for the courier. Sending instructions.pickup records pickup from the front door if unattended. Only send them when that is what your customer wants.

Prices are worked out again at confirm

Updating a booking does not return new prices. When you confirm, Transdirect prices the booking again from its current details, and that is the amount charged. If you change items or postcodes after quoting, quote again to show your customer an up-to-date price.

Example request

curl -X PATCH https://api.transdirect.com.au/api/v5/bookings/623630 \
  -H "api-key: $TD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": {
      "name": "Sam Taylor",
      "company_name": "Example Books Pty Ltd",
      "address": "1 Martin Place",
      "phone": "0291234567",
      "email": "dispatch@example.com"
    },
    "receiver": {
      "name": "Jordan Lee",
      "address": "200 Collins Street",
      "phone": "0398765432",
      "email": "jordan@example.com"
    },
    "goods_description": "Books",
    "customer_reference": "ORDER-1042"
  }'

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

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

const { data: booking, error } = await patchApiV5BookingsById({
  path: { id: '623630' },
  body: {
    sender: { name: 'Sam Taylor', address: '1 Martin Place', phone: '0291234567', email: 'dispatch@example.com' },
    receiver: { name: 'Jordan Lee', address: '200 Collins Street', phone: '0398765432', email: 'jordan@example.com' },
    goods_description: 'Books',
    customer_reference: 'ORDER-1042',
  },
});

The SDK also exports putApiV5BookingsById with the same body.

Response

200 OK with the updated booking, in the same shape as get a booking. A draft still reads "status": "New" and "status_code": "new".

{
  "id": 623630,
  "booked_at": "2026-10-16T04:13:34.000Z",
  "booked_by": "sender",
  "created_at": "2026-10-16T04:13:34.000Z",
  "declared_value": 0,
  "insured_value": 0,
  "description": "Books",
  "items": [
    { "id": 46885332, "description": "Carton", "weight": 5, "length": 40, "width": 30, "height": 20, "quantity": 1 }
  ],
  "label": "/api/v5/bookings/623630/label",
  "notifications": { "email": false, "sms": false },
  "receiver": {
    "id": 69194890,
    "address": "200 Collins Street",
    "company_name": "",
    "email": "jordan@example.com",
    "name": "Jordan Lee",
    "postcode": "3000",
    "phone": "0398765432",
    "state": "VIC",
    "suburb": "MELBOURNE",
    "type": "residential",
    "country": "AU"
  },
  "sender": {
    "id": 69194889,
    "address": "1 Martin Place",
    "company_name": "Example Books Pty Ltd",
    "email": "dispatch@example.com",
    "name": "Sam Taylor",
    "postcode": "2000",
    "phone": "0291234567",
    "state": "NSW",
    "suburb": "SYDNEY",
    "type": "business",
    "country": "AU"
  },
  "pickup_window": ["2026-10-16T09:00:00.000Z", "2026-10-16T17:00:00.000Z"],
  "connote": "",
  "charged_weight": 0,
  "scanned_weight": 0,
  "special_instructions": "",
  "status": "New",
  "status_code": "new",
  "is_paid": false,
  "updated_at": "2026-10-16T04:13:34.000Z",
  "pickup_instructions": "",
  "tailgate_pickup": false,
  "tailgate_delivery": false,
  "courier": null,
  "customer_reference": "ORDER-1042"
}

When an address check flags something for your attention, the response also includes a pendingVisualChecks array.

Errors

Status	Body	Cause
400	{"errors":["Cannot update. Booking has been processed."]}	The booking has already been paid.
400	{"errors":["Item ID `99` is not exist."]}	An item id in items is not on this booking.
400	{"success":false,"error":{"name":"ZodError","message":"..."}}	The body failed validation: an unknown field, a goods_description over 80 characters, a non-positive weight or dimension, or an unknown address type. message is a JSON-encoded list of issues, each with a path and message.
400	{"error":{"name":"ZodError","issues":[...]},"requestId":"..."}	A new item line (no id) is missing one of description, weight, length, width, height or quantity.
401	{"error":"missing_api_key"} or {"error":"invalid_api_key"}	No key, or a key that is not active.
404	{"error":"booking_not_found"}	No booking with that id belongs to your account.
429	{"error":"rate_limited"}	More than 600 requests a minute on this key. Wait for the retry-after seconds.

Try it

Open the API Explorer, add your key, and find Partially update a booking.