chargeable_weight_calculator
Calculate air freight chargeable weight by comparing actual gross weight and volumetric weight to determine the billable amount.
Instructions
Calculate air freight chargeable weight — the greater of actual gross weight and volumetric weight, which is what airlines bill. Volumetric weight (kg) = (L x W x H in cm) / divisor; the IATA-standard divisor is 6,000 (1 CBM = 166.67 kg), while express integrators (DHL, FedEx, UPS) typically use 5,000.
Behavior: deterministic; per-piece volumetric weight is rounded to 2 decimal places before totalling; basis reports which weight governs ("volumetric" = cargo is light for its size, "actual" = dense). Air mode only — sea W/M (1 CBM = 1,000 kg) is covered by consignment_calculator with mode=sea. Missing or non-positive inputs error with the failing parameter named. Rate-limited (anonymous use: 25 requests/day per IP): a 429 error body carries retry_after_seconds and a Retry-After header — back off and retry, or call get_subscribe_link for higher limits.
Returns: chargeable_weight_kg, basis, volumetric_weight_kg (total and per piece), gross_weight_kg, cbm, ratio, factor and pieces under result; normalized_input echoes the interpreted inputs and any defaults applied; plus confidence, _source and citation (the FreightUtils v1 response envelope).
Related: cbm_calculator (volume only), consignment_calculator (multi-line, all modes), uld_lookup (the equipment the freight flies in).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| factor | No | Volumetric divisor in cm³/kg. Default: 6000 (IATA standard); express carriers typically 5000. | |
| pieces | No | Number of identical pieces. Default: 1. | |
| width_cm | Yes | Width of one piece in centimetres (> 0). Example: 80. | |
| height_cm | Yes | Height of one piece in centimetres (> 0). Example: 100. | |
| length_cm | Yes | Length of one piece in centimetres (> 0). Example: 120. | |
| gross_weight_kg | Yes | Actual gross weight of the WHOLE shipment (all pieces) in kilograms. Example: 500. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| result | Yes | ||
| _source | Yes | ||
| citation | Yes | ||
| validity | No | ||
| warnings | No | ||
| confidence | Yes | ||
| blocking_errors | No | ||
| envelope_version | Yes | ||
| normalized_input | No |