What we can price, and what to send¶

One section per mode: what it covers, what it needs, and a complete request. Everything here is the API's own contract — the same table the tools are built from.

An assistant reads this from freightright://reference/cargo and freightright://reference/codes; it is here so a person can read it too.

Choosing a mode¶

Mode	What it is	Priced instantly?
FCL	Full container load, by sea — you pay for whole containers	Yes
LCL	Less than container load, by sea — your goods share a container	Yes
AIR	Air freight, airport to airport or door to door	Yes
LTL	Less than truckload, by road, door to door inside the US and Canada	Yes
FTL	A full truck, door to door in the US, Canada and Mexico	No — a quote request

A shipment's transport_mode is a different vocabulary: SEA is the kind of move FCL and LCL price, ROA/TRK the kind LTL and FTL price. A price check creates nothing — it never becomes a shipment.

Where it starts and ends¶

Either end is a PORT (a UN/LOCODE like CNSHA, or an airport IATA code like PVG) or a DOOR (a postal code and a country). Choosing PORT or DOOR is what decides the service scope; there is nothing else to ask for.

Never guess a code. freightright_find_locations turns "Shanghai" into CNSHA and PVG, and says which is the airport.

FCL — containers¶

Containers are 20GP, 40GP, 40HC (high cube) and 45HC, as a type and a quantity, at most four entries. FCL needs direction — IMPORT when you are buying the goods, EXPORT when you are selling them.

{
  "mode": "FCL",
  "origin": {"type": "PORT", "code": "CNSHA"},
  "destination": {"type": "PORT", "code": "USLAX"},
  "direction": "IMPORT",
  "containers": [{"type": "40HC", "quantity": 2}],
  "commodity": "Office chairs",
  "insured_value_usd": "25000.00",
  "customs_brokerage": true
}

FCL is priced for general cargo only. Hazardous or temperature-controlled goods are a quote request.

LCL and AIR — piece groups, or totals¶

A piece group is any number of identical pieces with the dimensions and weight of one of them. A uniform shipment is a single group, however many pallets it is. At most 50 groups.

{
  "mode": "LCL",
  "origin": {"type": "PORT", "code": "CNSHA"},
  "destination": {"type": "DOOR", "postal_code": "90021", "country_code": "US"},
  "direction": "IMPORT",
  "pieces": [
    {
      "quantity": 4,
      "package_type": "PALLET",
      "length": "120", "width": "100", "height": "150", "dimension_unit": "CM",
      "unit_weight": "400", "weight_unit": "KG"
    }
  ],
  "delivery_accessorials": ["LIFTGATE"]
}

When the piece dimensions are not known, send the shipment as totals instead — never both:

{"totals": {"pieces": 12, "weight": "1250.5", "weight_unit": "KG", "volume": "6.2", "volume_unit": "CBM"}}

LTL — handling units, door to door¶

LTL is a DOOR at both ends, inside the US and Canada, and always pieces with dimensions — no totals. At most 30 groups. It takes no direction, no incoterm and no insurance: for insurance on a truckload, send a quote request and say so in the note.

{
  "mode": "LTL",
  "origin": {"type": "DOOR", "postal_code": "90021", "country_code": "US"},
  "destination": {"type": "DOOR", "postal_code": "10001", "country_code": "US"},
  "pieces": [
    {
      "quantity": 2,
      "package_type": "PALLET",
      "length": "48", "width": "40", "height": "60", "dimension_unit": "IN",
      "unit_weight": "400", "weight_unit": "LB",
      "freight_class": "70"
    }
  ],
  "pickup_accessorials": ["LIFTGATE"],
  "delivery_accessorials": ["RESIDENTIAL", "APPOINTMENT"]
}

A freight class is not a price setting

It is classified from the density, handling, stowability and liability of the goods. Leave it out and it is estimated from the dimensions and weight you gave. Choosing a lower class to get a cheaper price is a misdeclaration — the carrier reweighs the shipment and rebills it.

FTL — a quote request¶

Full truckload has no instant price. The equipment goes in containers as container sizes — that is how the API takes it today — and everything else about the truck goes in the note.

{
  "shipment": {
    "mode": "FTL",
    "origin": {"type": "DOOR", "postal_code": "90021", "country_code": "US"},
    "destination": {"type": "DOOR", "postal_code": "64000", "country_code": "MX"},
    "containers": [{"type": "40GP", "quantity": 1}],
    "hazardous": true
  },
  "note": "Dry van, 42,000 lb, UN1993 class 3 packing group III. Needs insurance for USD 60,000."
}

Units and precision¶

Weight KG or LB · dimensions CM or IN · volume CBM or CFT. Decimals accepted: dimensions 2 places, weight 3, volume 4, money 2. More than that is refused rather than rounded — a rounded weight is a different shipment.

Extras¶

What	Where	Which modes
Insurance	`insured_value_usd`, the commercial value in USD	FCL, LCL, AIR only
Customs clearance	`customs_brokerage`, `customs_bond` (`SINGLE` or `ANNUAL`, US imports)	FCL, LCL, AIR
Port charges	`origin_port_charges`, `destination_port_charges`	FCL, LCL, AIR
Accessorials	`pickup_accessorials`, `delivery_accessorials` — `LIFTGATE`, `RESIDENTIAL`, `LIMITED_ACCESS`, `INSIDE`, `APPOINTMENT`	Needs a DOOR at that end; FCL accepts `RESIDENTIAL` only
Hazardous	`hazardous`	LCL, AIR, LTL, FTL — never FCL
Temperature control	`temperature_controlled`	LCL, AIR, FTL — never LTL