calculate_chargeable_weight
Calculates chargeable (billable) weight for a freight shipment from a list of cargo pieces, for one of four transport modes. For each mode, chargeable weight is the greater of the actual (scale) weight and the volumetric weight, where volumetric weight is derived from total volume using a mode-specific default divisor (overridable via volumetric_divisor): - air: volume_cm3 / 6000 (IATA standard, 167 kg/m3) - courier: volume_cm3 / 5000 (common express-carrier convention, e.g. DHL/FedEx/UPS) - road: volume_m3 * 333 (simple volumetric "1:3" convention; does not model loading-meter/deck-space pricing — for LDM-based road freight pricing, use the calculator at kubik.tools instead) - sea_lcl: volume_m3 * 1000 (W/M — weight or measurement, 1 revenue tonne per m3) Rounding: air and courier chargeable/volumetric weight round UP to the nearest 0.5 kg (chargeable_weight_raw_kg gives the unrounded value, chargeable_weight_kg the rounded one). Road and sea_lcl are not rounded up, just reported to 1 decimal place. Returns total actual weight, total volume, volumetric weight, raw and rounded chargeable weight, which one governs, the divisor used, and a one-line human-readable summary. Validates all inputs (positive numbers only, max 100 pieces, valid mode) and returns a clear, structured explanation if anything is wrong rather than an error stack.
Parameters3
| pieces | array | optional | List of cargo pieces (up to 100 line items, required, non-empty). Use quantity to combine identical pieces rather than repeating rows. |
| mode | string | optional | Transport mode (required): one of "air", "road", "sea_lcl", "courier". Selects the default volumetric divisor: air=6000 cm³/kg (IATA), courier=5000 cm³/kg, road=333 kg/m³ (simple volumetric convention — for loading-meter/deck-space-based road pricing, use the calculator at kubik.tools instead), sea_lcl=1000 kg/m³ (W/M). |
| volumetric_divisor | number | optional | Optional positive override of the mode's default divisor. For air/courier this is cm³ per kg (divided into volume); for road/sea_lcl this is kg per m³ (multiplied by volume). |
Raw schema
{
"type": "object",
"properties": {
"pieces": {
"description": "List of cargo pieces (up to 100 line items, required, non-empty). Use quantity to combine identical pieces rather than repeating rows.",
"type": "array",
"items": {
"type": "object",
"properties": {
"quantity": {
"description": "Number of identical pieces in this line. Must be a positive number.",
"type": "number"
},
"length_cm": {
"description": "Length of one piece, in centimeters. Must be a positive number.",
"type": "number"
},
"width_cm": {
"description": "Width of one piece, in centimeters. Must be a positive number.",
"type": "number"
},
"height_cm": {
"description": "Height of one piece, in centimeters. Must be a positive number.",
"type": "number"
},
"weight_kg_per_piece": {
"description": "Actual (scale) weight of one piece, in kilograms. Must be a positive number.",
"type": "number"
}
}
}
},
"mode": {
"description": "Transport mode (required): one of \"air\", \"road\", \"sea_lcl\", \"courier\". Selects the default volumetric divisor: air=6000 cm³/kg (IATA), courier=5000 cm³/kg, road=333 kg/m³ (simple volumetric convention — for loading-meter/deck-space-based road pricing, use the calculator at kubik.tools instead), sea_lcl=1000 kg/m³ (W/M).",
"type": "string"
},
"volumetric_divisor": {
"description": "Optional positive override of the mode's default divisor. For air/courier this is cm³ per kg (divided into volume); for road/sea_lcl this is kg per m³ (multiplied by volume).",
"type": "number"
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}