Customs declaration

Endpoint

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

Creates a customs declaration for an international booking. This is required for shipments where the sender or receiver is outside Australia.

Authentication

Path parameters

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

Request body

Field	Type	Required	Description
`contents_type`	string	Yes	Type of contents: `"gift"`, `"documents"`, `"merchandise"`, `"sample"`, `"return"`, or `"other"`.
`contents_description`	string	Yes	Description of the contents (e.g. `"Clothing and accessories"`).
`currency`	string	No	Currency code for declared values. Defaults to `"AUD"`.
`items`	array	Yes	Array of customs item objects.

Customs item object

Field	Type	Required	Description
`description`	string	Yes	Description of the item (e.g. `"Cotton t-shirt"`).
`quantity`	integer	Yes	Number of units.
`weight`	string	Yes	Weight per unit in kilograms.
`value`	string	Yes	Value per unit in the specified currency.
`country_of_origin`	string	Yes	ISO 3166-1 alpha-2 country code where the item was manufactured (e.g. `"AU"`, `"CN"`).
`hs_code`	string	No	Harmonised System tariff code for the item.

Example request

curl -X POST \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents_type": "merchandise",
    "contents_description": "Clothing and accessories",
    "currency": "AUD",
    "items": [
      {
        "description": "Cotton t-shirt",
        "quantity": 5,
        "weight": "0.2",
        "value": "25.00",
        "country_of_origin": "AU",
        "hs_code": "6109.10"
      },
      {
        "description": "Leather belt",
        "quantity": 2,
        "weight": "0.3",
        "value": "45.00",
        "country_of_origin": "AU"
      }
    ]
  }' \
  https://www.transdirect.com.au/api/bookings/v4/12345678/custom_declaration

Example response

{
  "id": 12345678,
  "customs_declaration": {
    "contents_type": "merchandise",
    "contents_description": "Clothing and accessories",
    "currency": "AUD",
    "items": [
      {
        "description": "Cotton t-shirt",
        "quantity": 5,
        "weight": "0.2",
        "value": "25.00",
        "country_of_origin": "AU",
        "hs_code": "6109.10"
      },
      {
        "description": "Leather belt",
        "quantity": 2,
        "weight": "0.3",
        "value": "45.00",
        "country_of_origin": "AU",
        "hs_code": null
      }
    ]
  }
}

When is a customs declaration required?

A customs declaration is required when:

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

The declaration provides customs authorities in the destination country with the information they need to assess duties and taxes.

Error responses

Status code	Description
`400`	Bad request — missing required fields or invalid values.
`401`	Unauthorised — invalid or missing credentials.
`404`	Not found — no booking exists with the given ID, or it belongs to another member.
`422`	Unprocessable entity — the booking is a domestic shipment and does not require a customs declaration.