Customs declaration

International parcel services need a customs declaration: who is sending, why, and what each line of goods is worth. Send it with a POST, and download the generated declaration as a PDF with a GET.

POST /api/v5/bookings/{id}/custom_declaration
GET /api/v5/bookings/{id}/custom_declaration

Requires your API key in the api-key header.

When to send it

The booking must be international (sender or receiver outside Australia) and already have an international parcel courier, which it gets when you confirm. Before that, the POST returns Courier not yet set.

International document services (the TNT, Toll Priority and FedEx services with document in their courier id) do not take a customs declaration. For FedEx document services, send fedex_document_type at confirm instead.

Sending the declaration again replaces the earlier one, including all of its item lines.

Request body

Send JSON with Content-Type: application/json. You can send the fields at the top level, or wrapped in a custom_declaration object.

Field	Type	Required	Description
name	string	Yes	Sender or declarant’s name.
email	string	Yes	Sender’s email.
phone	string	Yes	Sender’s phone.
company_name	string	No	Sender’s business name.
street_number	string	Yes	Street number of the sender’s address, for example 1.
street_name	string	Yes	Street name, for example Martin.
street_type	string	Yes	Street type, for example Pl, St or Rd.
suburb, state, postcode, country	string	No	Rest of the sender’s address.
booking_party_details_type	string or integer	No	commercial (or 1) for a business, private (or 0) for an individual. Default commercial.
reason_of_shipment	string	Yes	Why the goods are being sent, for example Sale, Gift or Sample.
items	array	Yes	At least one goods line. See below.

Each entry in items:

Field	Type	Required	Description
item	string	Yes	Name of the goods.
invoice_description	string	Yes	Customs description of the goods.
quantity	integer	Yes	Number of units. At least 1.
weight	number	Yes	Weight in kg. Greater than 0.
invoice_value	number	Yes	Value per unit in AUD. Greater than 0.
manufacturer_country	string	Yes	Country of manufacture.

Example request

curl -X POST https://api.transdirect.com.au/api/v5/bookings/623630/custom_declaration \
  -H "api-key: $TD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sam Taylor",
    "email": "dispatch@example.com",
    "phone": "0291234567",
    "company_name": "Example Books Pty Ltd",
    "street_number": "1",
    "street_name": "Martin",
    "street_type": "Pl",
    "suburb": "SYDNEY",
    "state": "NSW",
    "postcode": "2000",
    "country": "AU",
    "booking_party_details_type": "commercial",
    "reason_of_shipment": "Sale",
    "items": [
      {
        "item": "Paperback books",
        "invoice_description": "Printed books",
        "quantity": 4,
        "weight": 0.5,
        "invoice_value": 25,
        "manufacturer_country": "AU"
      }
    ]
  }'

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

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

const { data, error } = await postApiV5BookingsByIdCustomDeclaration({
  path: { id: '623630' },
  body: {
    name: 'Sam Taylor',
    email: 'dispatch@example.com',
    phone: '0291234567',
    street_number: '1',
    street_name: 'Martin',
    street_type: 'Pl',
    reason_of_shipment: 'Sale',
    items: [
      { item: 'Paperback books', invoice_description: 'Printed books', quantity: 4, weight: 0.5, invoice_value: 25, manufacturer_country: 'AU' },
    ],
  },
});

Response

200 OK

{
  "status": "success",
  "message": "Custom Declaration Successfully created"
}

Download the declaration

GET /api/v5/bookings/{id}/custom_declaration returns the declaration as an inline PDF (Content-Type: application/pdf).

curl https://api.transdirect.com.au/api/v5/bookings/623630/custom_declaration \
  -H "api-key: $TD_API_KEY" \
  -o customs-623630.pdf

With the SDK, getApiV5BookingsByIdCustomDeclaration returns the PDF as a Blob in data.

Errors

Status	Body	Cause
400	{"errors":["Custom Declaration is only applicable to international bookings."]}	Both addresses are in Australia.
400	{"errors":["Courier not yet set."]}	The booking has not been confirmed with a courier yet.
400	{"errors":["Courier service provided does not support international shipping."]}	The booking’s courier is not an international parcel service.
400	{"errors":["Document courier services does not apply customs declaration."]}	The courier is a document service, which does not take a declaration.
400	{"success":false,"error":{"name":"ZodError","message":"..."}}	A required field is missing or empty, or a number is not positive.
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.

Try it

Open the API Explorer, add your key, and find Create or update a booking custom declaration.