Hazardous Materials
Designate the contents of a package as hazmat when calling the Shipium APIs.
About hazardous materials
Hazardous material (hazmat) is any substance that can pose an unreasonable risk to health, safety, and property when transported in commerce. Due to its potential safety concerns, hazmat often must meet packaging and labeling requirements set by the U.S. Department of Transportation (DOT). Shipium suggests providing as much information as possible when shipping hazmat to meet any rules and regulations related to their transport and checking with your carrier representative for carrier-specific requirements.
Shipium handles shipping the most common types of hazmat, including:
- Limited quantities (LQ) products. LQ is also known as ORMD, although this term was phased out in January 2021. Examples include small cosmetics and some healthcare products.
- Lithium ion products. A common example is lithium ion batteries found in many electronics items, for which we simplify some details for you.
- Generalized hazardous material. You can specify International Air Transport Association (IATA) and DOT details for any hazardous materials directly.
Specify LQ/ORMD product for U.S. domestic shipping
As a shortcut, Shipium supports adding a productDetails
array entry of limited_quantity
. See the LQ example below.
Specify hazardous materials (hazmat)
Hazmat information is provided within shipments as part of the orderItemProperties
map, either using the standard Shipment construction or using the more popular Carrier and Method Selection & Shipment Labels mechanism.
Shipium generally recommends including as much data as you have for hazmat information as requirements differ among carriers. At a minimum, though, the following fields should be provided in your shipping request: category
, quantity
, quantityType
, quantityUnits
, and containerType
.
In addition to these and other item properties that are passed, such as productId
, you can specify a set of hazmat-related properties to ensure that these products are properly handled at the carrier level and during carrier selection.
There are two ways to do this:
-
For common hazmat classes, Shipium provides a shortcut mechanism and does much of the lookup on your behalf. The most common of these is the lithium ion classes for common electronics items, specified by the
category
property. The properties are included in the Pre-Configured Hazmat Properties section of this document. -
You can specify detailed hazardous materials properties using the properties defined in the Detailed Hazmat Properties section of this document and setting the
category
property to the valuedefined
.
Pre-configured hazmat properties
The following table includes properties for common hazmat classes covered by the shortcut mechanism.
property | propertyContents | parentProperty |
---|---|---|
"hazmat" | Booleantrue if the item is hazmatfalse if it is not (default) | orderItems array element |
"hazmatInfo" | JSON object (map) Contains information about this particular orderItems element.See properties below that have a parentProperty of hazmatInfo for details. | orderItems array element |
"category" | Hazmat category for this orderItems element. Values are:contains_lithium_ion contains_lithium_metal lithium_ion_battery_only lithium_metal_battery_only packaged_lithium_ion packaged_lithium_metal dry_ice For any of these hazmat categories, values must be provided for the quantity , quantityType , and quantityUnits fields.See the table below for additional details about these hazmat categories. | hazmatInfo |
"quantity" | Float value The quantity of hazmat material in this orderItems element in units of quantityType of quantityUnits | hazmatInfo |
"quantityType" | String enumeration The type of quantity of hazardous material. Values are: gross net | hazmatInfo |
"quantityUnits" | String enumeration The units of measure for the quantity of hazardous material specified. Values are: g kg lb oz ml l | hazmatInfo |
The following table provides information about Shipium's hazmat categories, including their proper shipping name, United Nations (UN) number, and transport mode. For each of the categories listed, the hazard class is class_9_miscellaneous
.
Category name | Proper shipping name | UN number | Transport mode |
---|---|---|---|
contains_lithium_ion | Lithium ion batteries contained in equipment | UN3481 | passenger_and_cargo_aircraft |
contains_lithium_metal | Lithium metal batteries contained in equipment | UN3091 | passenger_and_cargo_aircraft |
lithium_ion_battery_only | Lithium ion batteries (refers to lithium ion batteries that are not packed with or installed in equipment) | UN3480 | cargo_aircraft_only |
lithium_metal_battery_only | Lithium metal batteries (refers to lithium metal batteries that are not rechargeable and are shipped by themselves) | UN3090 | cargo_aircraft_only |
packaged_lithium_ion | Lithium ion batteries packed with equipment | UN3481 | passenger_and_cargo_aircraft |
packaged_lithium_metal | Lithium metal batteries packed with equipment | UN3091 | passenger_and_cargo_aircraft |
dry_ice | Dry ice | UN1845 | passenger_and_cargo_aircraft |
Detailed hazmat properties
If your shipment contains hazardous materials that cannot be included using the above pre-configured interface, you can use the properties in the following table to specify the details and set the category
property to the value defined
.
property | propertyContents | parentProperty |
---|---|---|
"hazmat" | Booleantrue if the item is hazmatfalse if it is not (default) | orderItems array element |
"hazmatInfo" | JSON object (map) Contains information pertaining to this particular orderItems element; properties related to this element are explained in this table. | orderItems array element |
"category" | String enumeration To specify detailed information, set this to defined . | hazmatInfo |
"hazmatId" | String Required if category is defined ; the IATA or DOT regulatory identifier for the commodity as appropriate (e.g., UN1755) | hazmatInfo |
"containerType" | String enumeration Required if category is defined ; one of the following strings for the material in which the hazardous material is packaged:fiberboard_box wooden_box plastic_jerrican metal_box steel_drum other plastic_box plastic_drum styrofoam_box cylinder envirotainer plywood_box aluminum_drum aluminum_cylinder plastic_pail plywood_drum fiber_drum steel_jerrican aluminum_jerrican steel_box carton aluminum_box | hazmatInfo |
"packingGroup" | String enumeration The degree of danger the hazardous material presents. Values are: i ii iii | hazmatInfo |
"packingInstructionCode" | String The packing instruction code used for air transport (e.g., 967) | hazmatInfo |
"properShippingName" | String Required if category is defined ; the proper shipping name that is associated with the specified hazmatId | hazmatInfo |
"hazardClass" | String enumeration Required if category is defined ; the hazard class of the hazmat. Values are:class_1_explosive class_2_flammable_gas class_3_flammable_liquid class_4_flammable_solid class_5_organic_peroxide class_6_poisonous_material class_7_radioactive class_8_corrosive_material class_9_miscellaneous | hazmatInfo |
"subsidiaryClasses" | Array of strings The appropriate IATA/DOT subsidiary classes associated with the material and the hazard class (e.g., 8.1) | hazmatInfo |
"quantity" | Float value Required if category is defined ; the quantity of hazmat material in this orderItems element in units of quantityType of quantityUnits | hazmatInfo |
"quantityType" | string enumeration Required if category is defined ; the type of quantity of hazardous material. Values are:gross net | hazmatInfo |
"quantityUnits" | String enumeration Required if category is defined ; the units of measure for the quantity of hazardous material specified. Values are:g kg lb oz ml l | hazmatInfo |
"transportMode" | String enumeration Required if category is defined ; the packing instruction code used for air transport. Values are:cargo_aircraft_only ground passenger_and_cargo_aircraft | hazmatInfo |
Examples
Non-hazmat example
This example in JavaScript Object Notation (JSON) shows a sample orderItems
entry for a shipment that contains no hazmat items.
"orderItemQuantities": [
{
"productId": "PRODUCTID001",
"quantity": 1
},
{
"productId": "PRODUCTID002",
"quantity": 2
},
]
Hazmat example: Limited quantity (LQ)/ORMD via ground transport
This example in JSON shows an orderItems
entry for a ground shipment that contains two items: one with no hazmat properties and one LQ/ORMD product.
"orderItemQuantities": [
{
"productId": "PRODUCTID001",
"quantity": 1
},
{
"productId": "PRODUCTID002",
"quantity": 2,
"productDetails": ["limited_quantity"]
}
]
Hazmat example: Limited quantity (LQ)/ORMD via air transport
This example in JSON shows an orderItems
entry for an air shipment that contains two items: one with no hazmat properties and one LQ/ORMD product (dry ice). Hazmat information is generally required for dangerous goods shipments being transported via air service methods, even those with LQ/ORMD classification, so providing the hazmat information for items being shipped via air is highly recommended.
"orderItemQuantities": [
{
"productId": "PRODUCTID001",
"quantity": 1
},
{
"hazmat": true,
"hazmatInfo": {
"category": "dry_ice",
"quantity": 2.0,
"quantityType": "gross",
"quantityUnits": "g",
"containerType": "fiberboard_box"
},
"productId": "PRODUCTIDHAZ3",
"quantity": 3
}
]
Hazmat example: Product containing lithium ion batteries
This example in JSON shows an orderItems
entry for a shipment that contains two items: one with no hazmat properties and one with a lithium ion battery.
"orderItemQuantities": [
{
"productId": "PRODUCTID001",
"quantity": 1
},
{
"hazmat": true,
"hazmatInfo": {
"category": "contains_lithium_ion",
"quantity": 1.0,
"quantityType": "gross",
"quantityUnits": "g",
"containerType": "wooden_box"
},
"productId": "PRODUCTIDHAZ1",
"quantity": 3
}
]
Hazmat example: Detailed hazmat properties
This example in JSON shows an orderItems
entry for a shipment containing two items, one with a chromic acid solution and one with no hazmat properties. Note that category
is set to "defined"
.
"orderItemQuantities": [
{
"hazmat": true,
"hazmatInfo": {
"category": "defined",
"hazmatId": "UN1755",
"containerType": "aluminum_jerrican",
"packingGroup": "ii",
"packingInstructionCode": "851",
"properShippingName": "chromic acid solution",
"hazardClass": "class_8_corrosive_material",
"subsidiaryClasses": [
"8.1"
],
"quantity": 5.0,
"quantityType": "net",
"quantityUnits": "l",
"transportMode": "ground"
},
"productDetails": [],
"productId": "PRODUCTID001",
"quantity": 3
}
]
Resources
Your Shipium team member is available to help along the way. However, you might find these resources helpful:
Updated 8 days ago