API Update: New BOL Handling Units Array Support
| 10 October 2025 | Category: Release Notes
🚀 Release Notes: Bill of Lading API Update — New HandlingUnits Array Support
Release Date: October 2025
API method: POST /BillOfLading
Impact Level: Optional, backward-compatible
📘 Overview
The Bill of Lading (BOL) POST method has been enhanced to support a new array called HandlingUnits, allowing a more detailed and structured representation of freight at the handling-unit level (e.g., pallets, skids, crates).
- This enhancement enables users to define shipments that include handling units with specific dimensions and associated items — improving flexibility, clarity and alignment with operational workflows.
- The existing Items array remains fully supported for backward compatibility.
However, you must not use both Items and HandlingUnits within the same request payload.
🧩 Details of the Change
New Property: HandlingUnits
A new array, HandlingUnits, has been added to the BillOfLading object.
It provides a structured way to represent handling-level groupings of freight and associated items.
Example Structure:
“HandlingUnits”: [
{
“UnitType”: “PLT”,
“Dimensions”: [
{
“Count”: 2,
“Length”: “48”,
“Width”: “40”,
“Height”: “60”
}
],
“Items”: [
{
“IsHazmat”: false,
“Pieces”: 10,
“PackageType”: “Bag”,
“NMFCItemNumber”: “123456”,
“NMFCSubNumber”: “01”,
“Description”: “Plastic resin pellets”,
“Unna”: {
“UnnaNumber”: “UN3077”,
“UnnaDescription”: “Environmentally hazardous substance, solid, n.o.s.”,
“NosDescription”: “Plastic resin”
},
“Class”: “60”,
“Weight”: 800
}
]
}
]
Each handling unit may include one or more Dimensions and Items entries, allowing a detailed description of both the physical characteristics and content of each unit.
Existing Property: Items (Unchanged)
The Items array continues to be supported exactly as before.
Existing integrations using this property will continue to function without modification.
Example Structure:
“Items”: [
{
“IsHazmat”: false,
“Pieces”: 10,
“PackageType”: “Bag”,
“NMFCItemNumber”: “123456”,
“NMFCSubNumber”: “01”,
“Description”: “Plastic resin pellets”,
“Unna”: {
“UnnaNumber”: “UN3077”,
“UnnaDescription”: “Environmentally hazardous substance, solid, n.o.s.”,
“NosDescription”: “Plastic resin”
},
“Class”: “60”,
“Weight”: 800
}
]
⚙️ Usage Rules
| Rule | Description |
| ✅ Use either Items or HandlingUnits | Both structures are valid independently |
| ❌ Do not include both arrays in a single request | Doing so will result in a 400 Bad Request validation error |
| ✅ Backward compatible | Existing clients using Items do not need to make any changes |
| ✅ Forward compatible | New clients can adopt HandlingUnits for more detailed shipment modeling |
🧠 Migration Guidance
- If you currently use Items:
You can continue to do so — the API behavior remains unchanged. - If you want to switch to HandlingUnits:
Replace your existing Items array with a HandlingUnits array.
Each handling unit can define:- UnitType (e.g., PLT, SKD, CTN)
- Dimensions (count, length, width height)
- Associated Items with weight, NMFC info and HAZMAT details
- Validation Behavior:
If both Items and HandlingUnits are provided in the same request, the API will return an error similar to: - {
- “error”: “You can only provide Items array or HandlingUnits array, both arrays can’t be submitted at the same time”
- }
🧾 Example Comparison
Before (Using Items)
“Items”: [
{
“Pieces”: 5,
“PackageType”: “Box”,
“Description”: “Electrical components”,
“Class”: “85”,
“Weight”: 500
}
]
After (Using HandlingUnits)
“HandlingUnits”: [
{
“UnitType”: “PLT”,
“Dimensions”: [
{
“Count”: 1,
“Length”: “48”,
“Width”: “40”,
“Height”: “50”
}
],
“Items”: [
{
“Pieces”: 5,
“PackageType”: “Box”,
“Description”: “Electrical components”,
“Class”: “85”,
“Weight”: 500
}
]
}
]
📢 Summary
- 🆕 HandlingUnits array added to the Bill of Lading object
- ✅ Items array remains supported for backward compatibility
- 🚫 Do not include both arrays in the same API request
- ⚙️ Backward- and forward-compatible design
- 📦 Enables detailed handling-level shipment modeling (units, dimensions, items)
Learn more by visiting our documentation website: https://technology.rlcarriers.com/ Submit questions or concerns to the API team at: apisupport@rlcarriers.com