Describe your freight, line by line

Carriers care about more than counts and weights. Description, NMFC, packaging type, piece count: these drive the paperwork that follows the load from dock to dock. Until today, our shipment API only captured a fraction of it.

From now on, you can hand us the full picture on every line of every shipment. We carry it through to the carrier, the invoice, and the printed Bill of Lading.

This release is fully backwards-compatible. Send the new fields when you have them; leave them out when you don't. Nothing in your existing integration breaks.

Capture per-line-item freight detail

Real freight is rarely a single homogeneous block. When you ship multiple commodities or mix packaging on one load, your carriers expect per-line-item detail on the paperwork, and they bill against it. Each entry of orderComponents[] now accepts:

{
  "palletCount":   2,
  "poundsWeight":  3000,
  "dimensions":    { "length": 48, "width": 48, "height": 48 },

  "description":   "Stone NOI",
  "nmfcCode":      "90500-04",
  "packagingType": "Pallets",
  "pieceCount":    0
}

Field	What it does
`description`	Per-line description. Different commodities on the same load get their own row on every downstream document.
`nmfcCode`	NMFC commodity code. Carriers use it to validate classification and resolve disputes; sending it up front cuts down on reclasses and surprise billing adjustments.
`packagingType`	Free text packaging type (`Pallets`, `Boxes`, `Crates`, `Bags`, ...). What the dock actually sees on the trailer.
`pieceCount`	Loose pieces inside the component, separate from `palletCount`. Gives the receiver a number to verify against when the truck arrives.

Why it matters:

Per-line description means a multi-commodity load isn't crammed into a single overloaded description field, then untangled by hand at the dock.
NMFC, pieces, and packaging type match what your carrier already prints on their own paperwork, so the documents your customer receives line up cleanly with the documents the carrier files.

All four default to null. Existing single-component palletized loads render exactly as they do today.

Note on freight class. LTL class is calculated from density at quote time and stored on the order automatically. It is not accepted as user input on the shipment create call to avoid the quoted class diverging from the printed class.

Multi-commodity example

A single shipment of one pallet of stone + one pallet of finished tile:

POST /v1/shipper/shipment
{
  "...": "...",
  "orderComponents": [
    {
      "palletCount":   1,
      "poundsWeight":  3000,
      "description":   "Stone NOI",
      "nmfcCode":      "90500-04",
      "packagingType": "Pallets",
      "pieceCount":    0
    },
    {
      "palletCount":   1,
      "poundsWeight":  2200,
      "description":   "Ceramic floor tile",
      "nmfcCode":      "63010-02",
      "packagingType": "Pallets",
      "pieceCount":    40
    }
  ]
}

Each line gets its own row in the freight table on the printed BOL, with its own description, NMFC, and packaging.

Bonus: your reference number now prints on partner BOLs

If you already send refNumber on create, that value now renders on partner-branded Bill of Lading templates as {your refNumber} ({Oway order number}), side by side with our internal order number. No API change required: existing refNumber payloads pick this up automatically.

Field rules

All new fields are optional. When provided, they must satisfy:

Field	Rule
`orderComponents[].description`	string, up to 256 chars
`orderComponents[].nmfcCode`	string, up to 32 chars
`orderComponents[].packagingType`	string, up to 32 chars
`orderComponents[].pieceCount`	non-negative integer

Validation errors come back as the standard ProblemDetail shape with violations[] pointing at the offending path (e.g. orderComponents[0].pieceCount).

How to adopt

Start populating the per-component fields for the commodities you ship most often. NMFC up front prevents reclassification disputes; per-line description and piece counts give your receivers something to verify against.
Confirm your refNumber matches your BOL number if you want it printed on partner BOLs. Most TMS exports already populate it correctly.

Questions, edge cases, or want help mapping your TMS export to our schema? Reach out at [email protected].