| name | freight-cost |
| description | Turn a freight rate into a cost per unit and a landed cost, by dividing the rate by a computed pallet or container load. Handles per-container (FCL), per-CBM (LCL groupage), per-pallet, per-kg air/road chargeable weight, quantity price breaks, duty on CIF, and the LCL-versus-FCL crossover quantity. Use whenever someone has a rate and wants cost per unit, landed cost, or to know whether a full container is worth it. |
Freight cost
Takes rates the user supplies and divides them by a load this plugin computes, so
the per-unit figure rests on real geometry rather than a guess at how much fits.
It quotes no rates of its own and reaches no network.
Command
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/freight.py cost \
--dims 400x300x250 --weight 6.5 --container 20gp --units 3000 \
--per-container 2400 --per-cbm 95 --min-cbm 2 \
--unit-price 4.20 --price-for 1000@3.95,2500@3.70 \
--duty-pct 12 --other 350 --currency USD
Pass every rate basis you have and the table ranks them by landed cost — that
comparison is usually the answer the user actually wants.
Rates
| Flag | Basis |
|---|
--per-container | All-in FCL rate for one box. Needs a load, so give --dims + --container, or state --units-per-container. |
--per-cbm with --min-cbm | LCL groupage. Almost every forwarder has a minimum billed volume; ask for it, 1-2 m3 is typical. |
--per-pallet | Pallet-rate road or groupage. |
--per-kg with --mode sea|air|road|courier | Billed on chargeable weight — the greater of actual and volumetric. Divisors: sea LCL 1 m3 = 1000 kg, air 167 kg/m3 (the IATA 6000 cm3/kg factor), road groupage 333 kg/m3, courier 200 kg/m3. Override with --divisor. |
--flat | One fixed charge for the shipment. |
--min-charge | Carrier minimum, applied to every basis. |
Goods and duties
| Flag | Meaning |
|---|
--unit-price | Single price per unit. |
--price-for QTY@PRICE | Quantity breaks, comma separated or repeated. The break that applies to the order quantity is the one used. |
--total-goods | Total value, when there is no per-unit price. |
--duty-pct | Duty rate. Charged on CIF by default (goods + freight), which is how the EU, UK and Israel assess it; --duty-base goods for FOB-based regimes. |
--other | Fixed charges: customs clearance, port fees, inland delivery, insurance. |
--currency | Label only — no conversion is done, so keep every input in one currency. |
Volume is measured the way it will be billed: on pallets you pay for the
footprint and the built height including the air under the top layer, and the
last part-filled pallet is costed on its own shorter build, not a full one.
Loose, you pay for the cartons.
Reading the output
per unit freight is the number to quote. landed/unit is goods +
freight + duty + other, and is the number that decides anything.% goods is freight as a share of goods value. Over about 25% the freight
is driving the decision, not the price the buyer negotiated — say so.- The crossover line appears when both
--per-cbm and --per-container are
given: the quantity past which a full container beats groupage, and whether
that quantity even fits in the container. When it does not, groupage wins at
every quantity and buying a container is a mistake.
What this cannot tell you
It divides; it does not price. Ocean and air rates move weekly, vary by lane,
carrier, season and surcharge, and no public source gives a carrier-specific
number for free. So:
- Get rates from a forwarder, and get them in writing with what is and is not
included. Ask specifically about origin charges, THC at destination,
documentation, ISPS and any peak-season surcharge — an all-in
--per-container
figure that omits destination charges is not all-in.
- Say which figures came from the user and which are geometry from this tool.
- Duty and VAT treatment vary by country and HS code; VAT is usually recoverable
for a registered business and duty never is, so do not add them together
without saying which is which. Confirm rates with a broker.
