Shipment Summary
shipment_summaryComposite shipment analysis in one call: volume (CBM), gross and chargeable weight, road LDM with pallet spaces and a vehicle suggestion (road mode), volumetric weight (air), revenue tonnes with a container suggestion (sea), dangerous-goods presence for items carrying un_number, and UK duty estimates for items carrying hs_code + customs_value.
Provide mode (road | air | sea | multimodal) and items[] (dims in cm, weight in kg PER ITEM, quantity; optional stackable, pallet_type, hs_code, un_number, customs_value PER ITEM, and adr_quantity — the TOTAL for the dangerous-goods line, all pieces together); origin/destination and incoterm refine the duty leg.
Behavior: calls the ldm_calculator, adr_lookup and uk_duty_calculator engines directly; CBM, volumetric weight and revenue tonnes are the same arithmetic inline rather than a call out. Road LDM uses the 2.40 m loading-metre convention divisor and, like ldm_calculator, treats an item with no stackable flag as NOT stacked. modeSpecific.palletSpaces is pallet FLOOR POSITIONS (the figure ldm_calculator reports); palletRows is the separate row count. The suggested vehicle is the smallest that holds the load by its length, its payload and its pallet floor positions — the record's own count when it is a floor count, otherwise worked from its deck (a 7.5t rigid holds 15 Euro pallets on the floor; modeSpecific.suggestedVehicleFloorPositions says which) — and trailerUtilisation is of that vehicle (utilisationBasis names it); the suggested container is the smallest dry box whose record holds the volume and payload. Sections that cannot run (e.g. duty without a customs value) surface in warnings instead of failing the whole call. Fields are checked by name: a field the tool does not read is refused with a tool error naming it and listing the accepted ones, never ignored. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.
Returns: mode, itemCount, totals {pieces, grossWeight, volumeCBM, chargeableWeight, billingBasis}, modeSpecific (LDM / pallet floor positions / pallet rows / suggested vehicle, or revenue tonnes / container), warnings and dataVersion (road mode attributes the vehicle dataset and the LDM divisor) under result — note this composite's result uses camelCase field names (legacy shape); plus confidence, _source and citation (the FreightUtils v1 response envelope).
Editions: edition ("2025" | "2027") and as_of (YYYY-MM-DD) choose the ADR edition — edition wins, else the date picks it (ADR 2025 before 2027-01-01, ADR 2027 from then; ADR 2025 may still be applied until 2027-06-30). An answer on a named edition carries adr_edition; neither sent, the answer is ADR 2025 until 2027-01-01.
Limitations: a planning summary, not a quotation or compliance determination.
Related: consignment_calculator (canonical snake_case lines[] shape with advisory flags), cbm_calculator, chargeable_weight_calculator, ldm_calculator, adr_lookup, uk_duty_calculator. ldm_calculator, adr_lookup and uk_duty_calculator are the engines this actually calls; the rest are the single-purpose equivalents of arithmetic it does inline.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Transport mode. Required unless the consignment object is sent. | |
| as_of | No | YYYY-MM-DD the answer is for (default today, UTC); picks the ADR edition when edition is omitted, and is echoed in the answer and its check receipt. | |
| items | No | Array of shipment items with dimensions, weight, and optional HS/UN codes. Required unless the consignment object is sent. | |
| origin | No | Origin location — ISO country code and optional UN/LOCODE | |
| edition | No | ADR edition: "2025" or "2027". Wins over as_of. Omit it and as_of picks the edition by the legal timeline: before 2027-01-01 ADR 2025; from 2027-01-01 ADR 2027 (ADR 2025 may still be applied until 2027-06-30 under 1.6.1.1 — edition "2025" answers on it until then); from 2027-07-01 ADR 2027 only. An ADR 2027 answer for a date before 2027-01-01 carries an EDITION_NOT_YET_APPLICABLE warning. | |
| incoterm | No | Incoterms 2020 three-letter code (e.g. 'DAP', 'EXW', 'FOB') | |
| consignment | No | Alternative to the other arguments: the consignment object (https://www.freightutils.com/schema/consignment-object.v1.json) — lines[] (description, un_number, packing_group, variant_index, quantity {value, unit, basis}, packages {count, type, gross_kg, un_mark}, hs_code, value {amount, currency}, dims, stackable, icao_limited_quantity, inner_packaging), journey {origin, destination, date, tunnels_on_route, mode}, vehicle, crew, options. Send it alone; an input the tool needs and the object lacks comes back in missing_inputs. | |
| destination | No | Destination location — ISO country code and optional UN/LOCODE | |
| freight_cost | No | Optional freight cost in GBP for duty calculation, 0 or more (default 0) | |
| insurance_cost | No | Optional insurance cost in GBP for duty calculation, 0 or more (default 0) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| _meta | No | ||
| as_of | No | ||
| result | Yes | ||
| status | No | ||
| _source | Yes | ||
| edition | No | ||
| citation | Yes | ||
| validity | No | ||
| warnings | No | ||
| confidence | Yes | ||
| missing_inputs | No | ||
| blocking_errors | No | ||
| envelope_version | Yes | ||
| normalized_input | No |