Customs declaration

Endpoint

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

Creates a customs declaration for an international booking. Required for shipments where the sender or receiver is outside Australia (and the selected courier supports customs declarations).

Authentication

Path parameters

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

Request body

Send the declaration either nested under custom_declaration (v4 PHP style) or as a flat body (v5 accepts both).

Declaration fields

Field	Type	Required	Description
`name`	string	Yes	Declarant / sender contact name.
`email`	string	Yes	Declarant email.
`phone`	string	Yes	Declarant phone.
`company_name`	string	No	Company name.
`street_number`	string	Yes	Street number of the declarant address.
`street_name`	string	Yes	Street name.
`street_type`	string	Yes	Street type (e.g. `"St"`, `"Rd"`, `"Ave"`).
`booking_party_details_type`	string \| integer	No	Party type: `1` / `"commercial"` for business, or `0` / `"private"` for individual. Defaults to commercial.
`reason_of_shipment`	string	Yes	Reason for export (e.g. sale, gift, sample).
`items`	array	Yes	Goods line items (at least one).
`postcode`	string	No	Declarant postcode.
`suburb`	string	No	Declarant suburb.
`state`	string	No	Declarant state.
`country`	string	No	Declarant country code.

Customs item object

Field	Type	Required	Description
`item`	string	Yes	Name of the goods line item.
`weight`	number	Yes	Weight per line in kilograms.
`quantity`	integer	Yes	Number of units.
`invoice_value`	number	Yes	Declared invoice value for the line.
`invoice_description`	string	Yes	Customs description of the goods.
`manufacturer_country`	string	Yes	Country of manufacture (ISO code or country name).

Example request

curl -X POST \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_declaration": {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "0400000000",
      "company_name": "Example Pty Ltd",
      "street_number": "123",
      "street_name": "George",
      "street_type": "St",
      "booking_party_details_type": "1",
      "reason_of_shipment": "sale",
      "items": [
        {
          "item": "Cotton t-shirt",
          "weight": 0.2,
          "quantity": 5,
          "invoice_value": 25.00,
          "invoice_description": "Cotton t-shirt",
          "manufacturer_country": "AU"
        },
        {
          "item": "Leather belt",
          "weight": 0.3,
          "quantity": 2,
          "invoice_value": 45.00,
          "invoice_description": "Leather belt",
          "manufacturer_country": "AU"
        }
      ]
    }
  }' \
  https://www.transdirect.com.au/api/bookings/v4/12345678/custom_declaration

Example response

A successful request returns 200 with a short confirmation (not an echo of the declaration body):

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

GET customs PDF

GET /api/bookings/v4/{id}/custom_declaration

Returns (or redirects to) the customs declaration PDF for the booking when one has been generated.

When is a customs declaration required?

A customs declaration is required when:

The receiver is in a country other than Australia, or
The sender is in a country other than Australia

…and the selected courier supports customs forms. Document-only international services may reject a declaration.

Error responses

Status code	Description
`400`	Bad request — missing required fields, domestic shipment, courier not set, or courier does not support customs. Response body includes an `errors` array.
`401`	Unauthorised — invalid or missing credentials.
`404` / `401`	Booking not found or not accessible.
`500`	Server error while processing the declaration.