Confirm a booking

v4 API

This page documents the v4 API (https://www.transdirect.com.au/api), the existing API — fully supported. For new integrations, prefer the v5 typed SDK. New to Transdirect? See v4 vs v5 — which should I use?. The v5 equivalent is the SDK function postApiV5BookingsV4ByIdConfirm.

Endpoint

POST /api/bookings/v4/{id}/confirm

Confirms a booking with a selected courier and pickup date. This triggers the payment process and submits the booking to the chosen courier.

Before confirming, ensure the booking has full sender and receiver details. Use update booking to add any missing information.

Authentication

Note

Requires authentication via API key or basic auth.

Path parameters

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

Request body

Field	Type	Required	Description
courier	string	Yes	Courier identifier from the quotes response (e.g. "allied", "couriers_please", "tnt_road_express"). Use the exact key from quotes — not a brand group name.
pickup-date	string	Yes	Desired pickup date in YYYY-MM-DD format. Must be one of the dates from the courier’s pickup_dates array. v4 requires this hyphenated name. v5 also accepts pickup_date (underscore) as an alias.
pickup-time	string	No	Pickup time window in HH:MM-HH:MM format (e.g. "09:00-17:00"). Optional — pass the value from the courier’s pickup_time field if provided. v5 also accepts pickup_time (underscore).
tier	integer	No	Frequent rate tier identifier. Only applicable for couriers that offer frequent rates (e.g. Couriers Please, Aramex).
payment_method	string	No	How to pay: "nab_<id>" / "paypal_<id>" (an id from GET /api/members/payment-methods), "credit" for your credit account, or "demo" for a demo booking. Omit to use the credit account. This is the recommended field — the same value works on create.
payment	object	No	Structured alternative to payment_method, still supported: { "method": "demo" }, { "method": "credit" }, { "method": "card", "card_id": N }, or { "method": "paypal", "agreement_id": N }. May be sent alongside payment_method if the two agree; naming different methods is a 400.

Caution

The confirm request uses hyphenated field names (pickup-date, pickup-time), unlike most other endpoints which use underscores. The response side (pickup_dates, pickup_time on quote objects) still uses underscores.

Example request

curl -X POST \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "courier": "allied",
    "pickup-date": "2025-08-18"
  }' \
  https://www.transdirect.com.au/api/bookings/v4/12345678/confirm

With frequent rate tier

curl -X POST \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "courier": "couriers_please",
    "pickup-date": "2025-08-18",
    "tier": 1
  }' \
  https://www.transdirect.com.au/api/bookings/v4/12345678/confirm

Response

A successful confirmation returns a 204 No Content status with no response body.

After confirmation, retrieve the booking to check its updated status and obtain the connote (consignment note number) once the courier has confirmed.

Access model

A confirmation results in a live booking only when you can pay for it. Say how with payment_method — see how payments work for the full picture:

• Charge a saved card or PayPal agreement — "nab_<id>" or "paypal_<id>", using the id verbatim from GET /api/members/payment-methods.
• Bill a credit account — "credit", or omit the field. Requires an approved Transdirect credit account with available credit.
• Confirm as a demo — "demo". No charge, never shipped.

curl -X POST \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "courier": "allied",
    "pickup-date": "2025-08-18",
    "payment_method": "nab_123"
  }' \
  https://www.transdirect.com.au/api/bookings/v4/12345678/confirm

If you nominate no payment method and have no credit account, the confirmation is refused with 403 Forbidden and an access_error code of NO_PAYMENT_METHOD. Having a card saved on your account is not enough on its own — the API charges a saved method only when you nominate it in the request. There is no manual approval step and nothing for support to enable; access is open by default.

A credit-account booking that would take you past your credit limit is refused the same way, with an access_error code of CREDIT_LIMIT_REACHED. Settle an outstanding invoice, or nominate a saved payment method on the request instead.

An unrecognised payment_method returns 400 rather than being ignored, so a typo can never silently become a credit-account attempt.

Demo mode

Note

To confirm a booking as a demo (sandbox) booking — no charge, not sent to a courier — you can either pass payment_method: "demo" when creating the booking, or select the demo courier here at confirm time by sending payment: { "method": "demo" } (or the payment_method: "demo" marker) in the confirm body. Demo bookings receive a DEMO-XXXXXXXX connote and a watermarked test label.

Choosing a courier

When selecting a courier, use the exact key returned in the quotes object from the create booking response. These are service-level identifiers (not brand group names). Examples of active services:

Identifier	Courier
allied	Allied Express
allied_pallet	Allied Pallet
couriers_please	Couriers Please
aramex	Aramex
tnt_road_express	TNT Road Express
tnt_overnight_express	TNT Overnight Express
tnt_nine_express / tnt_ten_express / tnt_twelve_express	TNT timed express
hunter_road_freight	Hunter Road Freight
northline	Northline
team_global_express	Team Global Express
direct_couriers_regular / _express / _elite	Direct Couriers

See list couriers for the full nested list of string_ids.

Tip

The pickup-date must be one of the dates returned in the courier’s pickup_dates array. Passing an unavailable date will result in an error.

Error responses

Status code	Description
400	Bad request — missing required fields or invalid courier/date.
401	Unauthorised — invalid or missing credentials. The message says which: credentials rejected, or none received.
402	Payment required — a supplied saved payment method was declined. The response includes a payment_error object.
403	Forbidden — no payment capability (no credit account / saved payment method), the credit limit has been reached, or API access has been disabled for the account. The response includes an access_error object with a code (NO_PAYMENT_METHOD, CREDIT_LIMIT_REACHED or API_ACCESS_DISABLED) and a user_message.
404	Not found — no booking exists with the given ID, or it belongs to another member.
422	Unprocessable entity — the booking is missing required details (e.g. sender/receiver address) or has already been confirmed.

Next steps

• Get the booking to check the updated status and connote
• Get the shipping label once the booking is confirmed
• Track the booking after pickup