Skip to content

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 send 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, and 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, which 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