Items and packaging

Every quote lists the parcels in items. Each item is one package type with its weight, dimensions and how many identical packages there are.

{
  "items": [
    { "description": "Carton", "weight": 5, "length": 40, "width": 30, "height": 20, "quantity": 3 }
  ],
  "goods_description": "Books"
}

Item fields

Field	Type	Unit	Notes
`description`	string		The package type, from the list below. Not what is inside.
`weight`	number	kilograms	Dead weight of one package.
`length`	number	centimetres
`width`	number	centimetres
`height`	number	centimetres
`quantity`	integer		How many identical packages.
`sku`	string		Optional. Your product SKU, saved on the item.

Send every dimension in centimetres and every weight in kilograms, never metres or grams.

If you leave out weight or a dimension, the default package size from your key’s module settings is used. A key with no default set uses 10 × 10 × 10 cm and 5 kg. Send real measurements: the courier charges on what it measures.

`description` and `goods_description`

These are different fields and both matter:

items[].description is the packaging, for example Carton, Satchel or Pallet.
goods_description (top level, or description at the top level) is what is inside, for example "Books" or "Machine parts".

Transdirect checks the goods description when a booking is confirmed, and some contents hold a booking for manual review before it goes to the courier.

Package types

Send one of these values as items[].description. Matching ignores case, so carton works, and carton/box is accepted as Carton.

Package type	Notes
`Carton`	A standard cardboard box.
`Wine/Beer/Liquor Carton`
`Carton containing Fragile goods`
`Carton containing Liquids`
`Carton containing Glass`
`Heavy Carton`	Still accepted. For a heavy item, consider a pallet, skid or crate instead (see heavy items).
`Skid`
`Pallet`
`Crate`
`Tube`
`Satchel`
`Satchel 250g`, `Satchel 500g`, `Satchel 1kg`, `Satchel 3kg`, `Satchel 5kg`	Sized satchels.
`Bag`
`Envelope`
`Other/Misc`	Bookings with this type can be held for manual review after payment.
`Unpackaged`	Accepted on a quote, but Transdirect does not carry unpackaged goods. Bookings with this type are held for manual review after payment. Package the goods and choose the matching type.

Some couriers only take some types. For example, Couriers Please and Aramex do not take pallets, skids or crates, and some freight couriers only take pallets, skids or crates. A courier that does not take your packaging is left out of the quote with serviceability: "items.not_serviced" in quote_errors.

Depending on your key’s module settings, a value that is not in the list is either rejected with 400 {"errors":{"items":["Invalid Item description."]}} or quoted as Carton. Always send a value from the list. Your key’s Package Type Rule settings in the members area can also replace the package type based on an item’s weight, or its cubic weight at 250 kg/m³ when that is higher.

Quantity and multiple items

Use quantity for identical packages rather than repeating the item. Use separate items for packages that differ in type, size or weight:

{
  "items": [
    { "description": "Carton", "weight": 5, "length": 40, "width": 30, "height": 20, "quantity": 3 },
    { "description": "Satchel 3kg", "weight": 2, "length": 40, "width": 30, "height": 5, "quantity": 1 }
  ]
}

Limits checked when you quote

Transdirect rejects the whole quote request with 400 when any item is over these limits:

Field	Maximum
`weight`	2000 kg
`length`, `width`, `height`	500 cm
`quantity`	999

The error names the field, for example:

{ "errors": { "items": [ { "weight": ["Weight must be 2000 kg or less."] } ] } }

A request with no items at all returns 400 {"errors":{"items":["Required"]}}.

Each courier also has its own weight and size limits. An item that one courier cannot take leaves that courier out of the quote, with items.over_limit or items.not_serviced in quote_errors, while other couriers still quote.

Rounding

Dimensions are rounded up to the next whole centimetre. A weight over 1 kg is rounded up to the next whole kilogram, so 5.2 kg is quoted as 6 kg. Weights of 1 kg or less are kept as sent. To keep decimal weights over 1 kg, tick Do not convert weight into whole number in your key’s module settings. Measure accurately and round up yourself if you want the quote to match exactly.

Heavy items and carton weight limits

Several couriers cap the weight of a single carton. Here “carton” means any packaging other than Pallet, Skid or Crate. When an item is over a courier’s limit, that courier is left out of the quote with items.not_serviced. Repack the item as a pallet, skid or crate to see more couriers.

The current limits, for the heaviest single item:

Courier	Residential (either address)	Business
TNT (all domestic services)	30 kg	35 kg
Team Global Express	29 kg	29 kg
Allied Express	35 kg	35 kg
Hunter Express Road Freight	35 kg	35 kg
Capital Transport	35 kg	35 kg
Direct Couriers	35 kg	35 kg

Transdirect can change these limits at any time, so rely on quote_errors rather than hard-coding them.

After payment, a booking can be held for manual review before it goes to the courier when an item other than a pallet, skid or crate is over 25 kg and the booked courier has no higher carton limit.

Tail lift

A tail lift (tailgate) truck can lift a heavy item on or off the truck when there is no forklift or loading dock. Ask for one in the quote request:

{
  "tailgate_pickup": true,
  "tailgate_delivery": false
}

Tail lift only applies when the heaviest single item is over 25 kg. For lighter shipments the two fields are ignored.
The tail lift charge is included in each quote’s total.
Some couriers cannot take your items with a tail lift. Their quote stays in the list with a tail_lift object, {"available": false, "reason": "weight", "message": "..."}, and confirming that courier returns 422 tail_lift_unavailable. Choose another courier, or remove the tail lift if there is a forklift.
If you leave out tailgate_pickup, your key’s Tail lift options setting for pickup can add it for items over 25 kg.
Bookings with tail lift are usually checked by Transdirect before they go to the courier.

Volumetric weight

Couriers charge on the greater of the dead weight and the volumetric (cubic) weight. Volumetric weight is the package volume multiplied by the courier’s conversion factor:

Volumetric weight (kg) = length (m) × width (m) × height (m) × conversion factor (kg per m³)

The factor depends on the courier, for example 250 kg/m³ for Team Global Express, 333 kg/m³ for Northline and 200 kg/m³ for international services. At 250 kg/m³, a 50 × 40 × 30 cm carton is 0.06 m³ × 250 = 15 kg, so a 10 kg item in that carton is charged as 15 kg.

The weight the courier charged on appears as charged_weight on the booking once it is known.

Packaging and dangerous goods

Transdirect only carries goods packed to its packaging requirements. The API does not check for dangerous goods, so ask your customers about them in your own interface and do not book goods the requirements exclude.