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.

🚧

Regulatory compliance

Shipium does not validate hazmat shipments against regulatory thresholds (watt-hours, lithium content, packing group, packaging instruction codes, etc.) at the API or carrier-eligibility layer. Customers are responsible for ensuring shipments comply with all applicable U.S. Department of Transportation (DOT), International Air Transport Association (IATA), and carrier-specific regulations. The carrier's own API may or may not validate at label-creation time, depending on the carrier.

Shipium supports the most common hazmat shipping pathways, including:

• Limited Quantity (LQ) and Limited Quantity Air (LQA) shipments. LQ is also known as ORMD, a legacy term phased out in January 2021. Common examples include cosmetics, perfumery products, and small consumer hazmat goods.
• Excepted Quantity (EQ) shipments. Small-volume hazmat under 49 CFR §173.4, eligible for reduced documentation; eligible on both ground and air
• Lithium battery shipments. Including the Small Battery Exception for air (SBEA) and ground (SBEG), as well as Fully Regulated lithium battery shipments; common in electronics shipments
• Generalized hazardous material. You can specify International Air Transport Association (IATA) and DOT details for any hazardous materials directly.

📘

Carrier-specific guidance for limited quantity shipments

Some carriers handle limited quantity (LQ) shipments differently than full hazmat shipments, particularly for ground services. For example, FedEx Ground services do not support dangerous goods special services for LQ lithium batteries; these ship as regular ground shipments. See carrier-specific documentation in the Carrier Network section for details.

productDetails reference

The productDetails field within orderItemQuantities allows you to flag products with special shipping characteristics. Shipium uses these values to filter carrier options, apply appropriate handling, and trigger carrier-specific surcharges.

Accepted values

For the rule on combining hazmat tags within a single shipment, see Hazmat tag exclusivity under Usage notes below.

Usage notes

• Preferred terminology. Use limited_quantity (or lq) for LQ/ORM-D items. The value ormd is still accepted for backward compatibility, but limited_quantity is recommended for new implementations.
• Multiple values. You can pass multiple values in the array if a product has more than one special characteristic. For example, a perishable item that is also limited quantity hazmat:

"orderItemQuantities": [
  {
    "productId": "PROD-12345",
    "quantity": 1,
    "productDetails": ["limited_quantity", "perishable"]
  }
]

• Hazmat tag exclusivity. A shipment can include only one of the following hazmat tags: limited_quantity (or its alias ormd), limited_quantity_air, excepted_quantity, small_battery_exception_air, or small_battery_exception_ground. Shipments combining two or more of these tags fail validation. Non-hazmat tags such as perishable or bound_printed_matter can still be combined with one hazmat tag.
• Full hazmat shipments. For items requiring complete hazmat documentation beyond LQ classification, use the hazmatInfo object instead of or in addition to productDetails. See the detailed hazmat properties example for detailed hazmat shipping requirements.

LQ/ORMD 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 using hazmatInfo

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 value defined.

Pre-configured hazmat properties

The following table includes properties for common hazmat classes covered by the shortcut mechanism.

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.

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.

The same hazmatInfo properties listed below also support the limited_quantity_air, excepted_quantity, small_battery_exception_air, and small_battery_exception_ground hazmat tags. Each property's description notes the hazmat tags that require it.

For a quick reference of which hazmatInfo properties are required for each hazmat tag, see Field requirements by hazmat tag below.

Field requirements by hazmat tag

The following table shows which hazmatInfo properties are required for each of the four hazmat tags. This can be used as a quick reference alongside the example payloads further down this page. In the table below:

• LQA refers to the limited_quantity_air hazmat tag
• EQ refers to the excepted_quantity hazmat tag
• SBEA refers to the small_battery_exception_air hazmat tag
• SBEG refers to the small_battery_exception_ground hazmat tag

For shortcut categories like contains_lithium_ion or dry_ice, see Pre-Configured Hazmat Properties above.

Emergency response info for hazmat shipments

When shipping hazardous materials, carriers may require a 24-hour emergency response phone number and contact details. Many companies use an Emergency Response Info Provider (ERIP) as their emergency contact rather than providing their own company phone number.

Shipium supports an optional emergencyResponseInfo object at the shipment level within shipmentParameters (or multiParcelShipmentParameters for multi-parcel shipments). This object allows you to specify emergency contact details that are transmitted to the carrier for hazmat shipments.

emergencyResponseInfo fields

The emergencyResponseInfo object is included directly in shipmentParameters, separate from the item-level hazmatInfo. All fields are optional.

Fallback behavior

If emergencyResponseInfo is not included in a hazmat shipment request, Shipium automatically falls back to the shipFrom contact information for carriers that require emergency details. This means that existing hazmat shipments will continue to work without modification, but providing explicit ERIP details is recommended for accuracy and compliance.

Carrier support

Emergency response contact fields are supported by UPS and FedEx.

UPS-specific guidance

Phone number formatting. UPS restricts certain characters in emergency phone numbers. Shipium automatically removes periods, dashes, plus signs, parentheses, spaces, and the keywords "EXT" and "OPT" before transmitting to UPS. You do not need to pre-sanitize phone numbers.

When emergency contact info is required. Although Shipium treats all emergencyResponseInfo fields as optional, UPS requires emergency phone and contact information for hazmat shipments where the origin or destination is within the US 50 states or Puerto Rico and the shipment uses the IATA regulation set (air transport). For ground domestic and Canada ground shipments, the fields are optional at the UPS level. If required fields are not provided and the shipFrom fallback does not contain adequate information, UPS may reject the shipment.

Examples

Non-hazmat example

This example in JavaScript Object Notation (JSON) shows a sample orderItemQuantities 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 shows an orderItemQuantities entry for a ground shipment that contains two items: one with no hazmat properties and one LQ/ORMD product. LQ/ORMD via ground does not require a hazmatInfo block; flagging the item with the limited_quantity productDetails tag is sufficient for carrier selection.

{
  "orderItemQuantities": [
    {
      "productId": "PRODUCTID001",
      "quantity": 1
    },
    {
      "productId": "PRODUCTID002",
      "quantity": 2,
      "productDetails": ["limited_quantity"]
    }
  ]
}

Hazmat example: Limited Quantity Air (LQA)

This example shows an orderItemQuantities entry for an air shipment containing one LQA item. LQA applies to Limited Quantity hazmat transported on air service methods under 49 CFR §172.315(b), the Y-mark pathway. Unlike LQ via ground, LQA requires a full hazmatInfo block on the item.

Use the limited_quantity_air productDetails tag, which is the air-pathway counterpart to limited_quantity for ground.

The required hazmatInfo fields for an LQA item are:

• hazmatId, the UN or ID number, such as UN1263
• properShippingName
• hazardClass
• packingGroup, one of i, ii, or iii
• transportMode, either passenger_and_cargo_aircraft or cargo_aircraft_only (ground is rejected for LQA)
• quantity, quantityType, and quantityUnits
• containerType
• numberOfInnerPackagings
• innerPackagingType
• outerPackagingType
• packingInstructionCode
• shipperDeclarationStatement, typically LQ_air or cargo_aircraft_only for LQA

👉

LQA does not apply to lithium batteries

Limited Quantity has no regulatory exception for batteries. For lithium-battery air-eligible shipments, use the small_battery_exception_air tag. For ground-only lithium-battery shipments, use the small_battery_exception_ground tag. See the Small Battery Exception examples below for battery-specific field requirements.

The following example shows a non-battery LQA payload for a paint product.

{
  "orderItemQuantities": [
    {
      "productId": "PRODUCTID001",
      "quantity": 1
    },
    {
      "hazmat": true,
      "hazmatInfo": {
        "hazmatId": "UN1263",
        "properShippingName": "Paint",
        "hazardClass": "class_3_flammable_liquid",
        "packingGroup": "ii",
        "transportMode": "passenger_and_cargo_aircraft",
        "quantity": 0.5,
        "quantityType": "net",
        "quantityUnits": "l",
        "containerType": "fiberboard_box",
        "numberOfInnerPackagings": 1,
        "innerPackagingType": "plastic bottle",
        "outerPackagingType": "fiberboard box",
        "packingInstructionCode": "Y344",
        "shipperDeclarationStatement": "LQ_air"
      },
      "productDetails": ["limited_quantity_air"],
      "productId": "PRODUCTIDHAZ1",
      "quantity": 1
    }
  ]
}

📘

Validation notes

Shipments fail validation if a required field is missing, if transportMode: ground is supplied with the limited_quantity_air tag, or if any other hazmat tag appears on the same item. Per-carrier eligibility is also evaluated against the configured LQA support on each service method.

LQA support varies by carrier; confirm with your Implementation team which carriers honor LQA on your account configuration.

Hazmat example: Excepted Quantity (EQ)

This example shows an orderItemQuantities entry for a shipment containing one EQ item. EQ applies to small-volume hazmat shipped under 49 CFR §173.4. EQ items are eligible for reduced documentation, exempt from carrier-side hazmat data transmission, and may ship by either ground or air.

Use the excepted_quantity productDetails tag.

The required hazmatInfo fields for an EQ item are:

• category, which must be defined; lithium shortcut categories such as contains_lithium_ion are rejected for EQ items
• hazmatId, the UN or ID number, such as UN1266
• properShippingName
• hazardClass
• packingGroup, one of i, ii, or iii
• transportMode, which can be either ground or air for EQ
• quantity, quantityType, and quantityUnits
• containerType
• shipperDeclarationStatement, typically EQ for EQ items

EQ items are exempt from the inner and outer packaging fields (numberOfInnerPackagings, innerPackagingType, outerPackagingType, packingInstructionCode) and from all battery fields.

👉

Carrier-side data transmission for EQ

When a carrier service method is configured to suppress hazmat details on the carrier API call, Shipium omits the hazmat block from the outbound request for EQ items. For UPS REST specifically, Shipium sets the regulated-level code to EQ and the carrier label does not print the "Dangerous Goods As Per Associated DGD" statement. Behavior on other carriers varies; confirm with your Implementation team for carrier-specific EQ handling on your account.

The following example shows an EQ payload for a perfumery product.

{
  "orderItemQuantities": [
    {
      "productId": "PRODUCTID001",
      "quantity": 1
    },
    {
      "hazmat": true,
      "hazmatInfo": {
        "category": "defined",
        "hazmatId": "UN1266",
        "properShippingName": "Perfumery products",
        "hazardClass": "class_3_flammable_liquid",
        "packingGroup": "iii",
        "transportMode": "ground",
        "quantity": 0.03,
        "quantityType": "net",
        "quantityUnits": "l",
        "containerType": "fiberboard_box",
        "shipperDeclarationStatement": "EQ"
      },
      "productDetails": ["excepted_quantity"],
      "productId": "PRODUCTIDHAZ2",
      "quantity": 1
    }
  ]
}

📘

Validation notes

Shipments fail validation if a required field is missing, if category is set to anything other than defined, or if any other hazmat tag appears on the same item.

EQ support varies by carrier; confirm with your Implementation team which carriers honor EQ on your account configuration.

Hazmat example: Small Battery Exception (Air)

This example shows an orderItemQuantities entry for a shipment containing one SBEA item. SBEA applies to lithium cells and batteries below regulated thresholds, shipped with the Lithium Battery Mark on the outer packaging, under 49 CFR §173.185(c)(1)(iii). SBEA items may ship by either air or ground.

Use the small_battery_exception_air productDetails tag.

The required hazmatInfo fields for an SBEA item are:

• category, which must be defined
• hazmatId, one of the lithium-battery UN numbers: UN3090, UN3091, UN3480, or UN3481
• properShippingName
• hazardClass, typically class_9_miscellaneous
• transportMode
• quantity, quantityType, and quantityUnits
• containerType
• numberOfInnerPackagings
• innerPackagingType
• outerPackagingType
• packingInstructionCode, typically an IATA Packing Instruction value such as 965 through 970
• shipperDeclarationStatement, typically small_battery_air for SBEA
• Battery fields: at least one of wattHours or lithiumContent is required, plus numberOfCells, numberOfBatteries, and batteryConfiguration

packingGroup is optional for SBE items. Section II of IATA Packing Instructions 965 through 970 (which cover the lithium-battery UN numbers above) does not assign a packing group, so SBEA items may omit this field. SBEA items that include packingGroup will pass validation; the field is informational only.

wattHours applies to lithium-ion batteries (UN3480, UN3481). lithiumContent applies to lithium-metal batteries (UN3090, UN3091). Customers ship one or the other depending on the battery chemistry.

The following example shows an SBEA payload for lithium-ion batteries packed with equipment.

{
  "orderItemQuantities": [
    {
      "productId": "PRODUCTID001",
      "quantity": 1
    },
    {
      "hazmat": true,
      "hazmatInfo": {
        "category": "defined",
        "hazmatId": "UN3481",
        "properShippingName": "Lithium ion batteries packed with equipment",
        "hazardClass": "class_9_miscellaneous",
        "packingGroup": "ii",
        "transportMode": "passenger_and_cargo_aircraft",
        "quantity": 0.5,
        "quantityType": "net",
        "quantityUnits": "kg",
        "containerType": "fiberboard_box",
        "numberOfInnerPackagings": 1,
        "innerPackagingType": "plastic bag",
        "outerPackagingType": "fiberboard box",
        "packingInstructionCode": "966",
        "shipperDeclarationStatement": "small_battery_air",
        "wattHours": 95.0,
        "numberOfCells": 4,
        "numberOfBatteries": 1,
        "batteryConfiguration": "packed_with_equipment"
      },
      "productDetails": ["small_battery_exception_air"],
      "productId": "PRODUCTIDHAZ3",
      "quantity": 1
    }
  ]
}

📘

Validation notes

Shipments fail validation if a required field is missing, if category is set to anything other than defined, or if any other hazmat tag appears on the same item. Shipium does not validate watt-hour or lithium-content values against the regulatory thresholds for SBEA eligibility; customers are responsible for confirming their batteries meet the §173.185(c)(1)(iii) limits.

SBEA support varies by carrier; confirm with your Implementation team which carriers honor SBEA on your account configuration.

Hazmat example: Small Battery Exception (Ground)

This example shows an orderItemQuantities entry for a ground shipment containing one SBEG item. SBEG applies to lithium cells and batteries shipped by ground only under 49 CFR §173.185(c)(1)(iv), with the "FORBIDDEN FOR TRANSPORT ABOARD AIRCRAFT AND VESSEL" mark on the outer packaging in place of the Lithium Battery Mark. SBEG is not eligible for any air service method.

Use the small_battery_exception_ground productDetails tag.

The required hazmatInfo fields for an SBEG item are:

• category, which must be defined
• hazmatId, one of the lithium-battery UN numbers: UN3090, UN3091, UN3480, or UN3481
• properShippingName
• hazardClass, typically class_9_miscellaneous
• transportMode, which must be ground
• quantity, quantityType, and quantityUnits
• containerType
• numberOfInnerPackagings
• innerPackagingType
• outerPackagingType
• shipperDeclarationStatement, set to small_battery_ground for SBEG
• Battery fields: at least one of wattHours or lithiumContent is required, plus numberOfCells, numberOfBatteries, and batteryConfiguration

wattHours applies to lithium-ion batteries (UN3480, UN3481). lithiumContent applies to lithium-metal batteries (UN3090, UN3091). Customers ship one or the other depending on the battery chemistry.

packingGroup and packingInstructionCode are optional for SBEG. Section II of IATA Packing Instructions 965 through 970 does not assign a packing group, and 49 CFR §173.185(c)(1)(iv) ground SBE is a DOT Special Provision rather than a Packing Instruction, so no IATA Packing Instruction code applies. SBEG items may omit both fields.

The following example shows an SBEG payload for lithium-ion batteries contained in equipment.

{
  "orderItemQuantities": [
    {
      "productId": "PRODUCTID001",
      "quantity": 1
    },
    {
      "hazmat": true,
      "hazmatInfo": {
        "category": "defined",
        "hazmatId": "UN3481",
        "properShippingName": "Lithium ion batteries contained in equipment",
        "hazardClass": "class_9_miscellaneous",
        "transportMode": "ground",
        "quantity": 1.2,
        "quantityType": "net",
        "quantityUnits": "kg",
        "containerType": "fiberboard_box",
        "numberOfInnerPackagings": 1,
        "innerPackagingType": "plastic bag",
        "outerPackagingType": "fiberboard box",
        "shipperDeclarationStatement": "small_battery_ground",
        "wattHours": 75.0,
        "numberOfCells": 6,
        "numberOfBatteries": 1,
        "batteryConfiguration": "contained_in_equipment"
      },
      "productDetails": ["small_battery_exception_ground"],
      "productId": "PRODUCTIDHAZ4",
      "quantity": 1
    }
  ]
}

📘

Validation notes

Shipments fail validation if a required field is missing, if category is set to anything other than defined, if transportMode is anything other than ground, or if any other hazmat tag appears on the same item. SBEG items are not eligible for air service methods. Shipium does not validate watt-hour or lithium-content values against the regulatory thresholds for SBEG eligibility; customers are responsible for confirming their batteries meet the §173.185(c)(1)(iv) limits.

SBEG support varies by carrier; confirm with your Implementation team which carriers honor SBEG on your account configuration.

Hazmat example: Product containing lithium ion batteries

This example in JSON shows an orderItemQuantities 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: Product containing dry ice

This example shows an orderItemQuantities entry for a shipment containing one item refrigerated with dry ice. Dry ice (UN1845) is solid carbon dioxide and ships under simplified handling on most ground service methods, with additional requirements on air service methods.

Use the dry_ice category shortcut in the hazmatInfo block. The shortcut populates the underlying dangerous-goods fields automatically; customers do not need to provide hazmatId, properShippingName, hazardClass, or packingGroup for dry ice items.

Required fields when using the dry_ice shortcut:

• category, set to dry_ice
• quantity, the net weight of dry ice in the package
• quantityType, set to net
• quantityUnits, typically kg or lb

👉

Carrier handling for dry ice

Dry ice handling differs by carrier and transport mode. Most ground services do not assess dangerous goods fees on dry ice; air service methods typically apply dry ice surcharges and may require additional documentation.

The following example shows a shipment with a perishable item refrigerated using dry ice.

{
  "orderItemQuantities": [
    {
      "hazmat": true,
      "hazmatInfo": {
        "category": "dry_ice",
        "quantity": 2.5,
        "quantityType": "net",
        "quantityUnits": "kg"
      },
      "productDetails": ["perishable"],
      "productId": "PRODUCTIDDRY1",
      "quantity": 1
    }
  ]
}

📘

Validation notes

Shipments fail validation if quantity is missing or zero, or if quantityUnits is not one of the supported weight units. Shipium does not validate dry ice quantities against carrier-specific weight limits for air transport; customers are responsible for confirming their shipments meet the applicable carrier and IATA limits.

Dry ice support varies by carrier; confirm with your Implementation team which carriers and service methods accept dry ice on your account configuration.

Hazmat example: Detailed hazmat properties

This example in JSON shows an orderItemQuantities 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
    }
]
}

Hazmat example: Shipment with emergency response info (ERIP)

This example in JSON shows a shipment containing a hazardous material with emergency response contact details provided at the shipment level. The emergencyResponseInfo object is included in shipmentParameters, while the hazmat item details remain in orderItemQuantities.

{
"shipmentParameters": {
    "emergencyResponseInfo": {
        "phoneNumber": "18005551234",
        "contactName": "CHEMTREC",
        "contractNumber": "CCN123456"
    },
    "currencyCode": "usd",
    "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:

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support