Hazardous Materials (Dangerous Goods)

RocketShipIt supports shipping hazardous materials (dangerous goods) for carriers that offer it. This includes creating hazmat shipping labels and getting rates that reflect Dangerous Goods surcharges such as lithium battery fees.

Note: Hazardous materials shipping is subject to strict regulations. Ensure you are familiar with the applicable regulations (CFR, IATA, ADR, TDG) for your shipments. RocketShipIt does not validate compliance — it is your responsibility to ensure all hazmat data is accurate.

Supported Carriers#

UPS (REST API)

Key Parameters#

Hazmat data is set at the package level using the hazmat object inside each package. Additionally, the hazmat_regulation_set parameter can be set at the request level as a default for all chemical records.

Parameter	Description
`hazmat_regulation_set`	Top-level default regulation set: `CFR`, `IATA`, `ADR`, or `TDG`
`hazmat.transport_mode`	Transport method: `Ground`, `CAO` (Cargo Aircraft Only), `PAX` (Passenger Aircraft), `Highway`
`hazmat.emergency_phone`	24-hour emergency response phone number
`hazmat.emergency_contact`	Emergency contact name
`hazmat.all_packed_in_one`	Set `true` if all hazmat items are packed in one package
`hazmat.overpack`	Set `true` if the package is an overpack
`hazmat.q_value`	Q-value for IATA AllPackedInOne (0.1–1.0)
`hazmat.outer_packaging_type`	Outer packaging type description (shipping labels only)
`hazmat.chemical_records`	Array of chemical records (max 3 per package for UPS)

Chemical Record Fields#

Each entry in chemical_records supports the following fields:

Parameter	Description
`identifier`	Unique identifier for this chemical record within the package
`regulation_set`	Per-chemical regulation set, overrides `hazmat_regulation_set`
`regulated_level_code`	`FR` (fully regulated), `LQ` (limited quantity), `LR` (lightly regulated), `EQ` (excepted quantity)
`id_number`	UN/NA/ID number (e.g., `UN3480`)
`proper_shipping_name`	DOT proper shipping name
`technical_name`	Technical/chemical name
`class_division_number`	Hazard class (e.g., `9`, `3`, `4.1`)
`sub_risk_class`	Subsidiary risk class
`packaging_group`	Packing group (`I`, `II`, or `III`)
`quantity`	Quantity of the hazardous material
`uom`	Unit of measure (e.g., `kg`, `ml`)
`packaging_instruction_code`	Packaging instruction code (e.g., `965`)
`packaging_type`	Type of inner packaging
`packaging_type_quantity`	Number of inner packages
`hazard_label`	Hazard label required indicator
`reportable_quantity`	Reportable quantity indicator (e.g., `RQ`)
`additional_description`	Additional description text
`transport_category`	Transport category
`tunnel_restriction_code`	Tunnel restriction code (e.g., `D/E`)

Hazmat Shipping Labels#

To create a hazmat shipping label use the SubmitShipment action with the hazmat object on the package. The outer_packaging_type field is only used for shipping labels, not rating.

{
  "carrier": "UPS-REST",
  "action": "SubmitShipment",
  "params": {
    "account_number": "YOUR_ACCOUNT_NUMBER",
    "key": "YOUR_UPS_API_KEY",
    "service": "03",
    "hazmat_regulation_set": "CFR",
    "packages": [
      {
        "weight": 25,
        "length": 10,
        "width": 10,
        "height": 10,
        "hazmat": {
          "transport_mode": "Ground",
          "emergency_phone": "8005551234",
          "emergency_contact": "Hazmat Response Team",
          "all_packed_in_one": true,
          "overpack": true,
          "q_value": "0.5",
          "outer_packaging_type": "FIBERBOARD BOX",
          "chemical_records": [
            {
              "identifier": "1",
              "regulation_set": "CFR",
              "regulated_level_code": "FR",
              "id_number": "UN3480",
              "proper_shipping_name": "Lithium ion batteries",
              "technical_name": "Lithium Ion",
              "class_division_number": "9",
              "sub_risk_class": "4.1",
              "packaging_group": "II",
              "quantity": "6",
              "uom": "kg",
              "packaging_instruction_code": "965",
              "packaging_type": "Fiberboard Box",
              "packaging_type_quantity": "1",
              "hazard_label": "Y",
              "reportable_quantity": "RQ",
              "additional_description": "Limited Quantity",
              "transport_category": "0",
              "tunnel_restriction_code": "D/E"
            }
          ]
        }
      }
    ],
    "shipper": "RocketShipIt",
    "ship_addr1": "123 Main St",
    "ship_city": "Whitehall",
    "ship_state": "MT",
    "ship_code": "59759",
    "ship_phone": "1231231234",
    "ship_country": "US",
    "to_name": "John Doe",
    "to_addr1": "940 Presidio Ave",
    "to_addr2": "#103",
    "to_state": "CA",
    "to_city": "San Francisco",
    "to_code": "94115",
    "to_country": "US",
    "test": true
  }
}

Hazmat Rating#

To get rates that include Dangerous Goods surcharges, use the GetAllRates action with the same hazmat object on the package. This is useful for quoting accurate shipping costs for orders containing hazardous materials like lithium batteries.

The request is nearly identical to the label request. The only differences are:

action is GetAllRates instead of SubmitShipment
outer_packaging_type is not used for rating

{
  "carrier": "UPS-REST",
  "action": "GetAllRates",
  "params": {
    "account_number": "YOUR_ACCOUNT_NUMBER",
    "key": "YOUR_UPS_API_KEY",
    "service": "03",
    "hazmat_regulation_set": "CFR",
    "packages": [
      {
        "weight": 25,
        "length": 10,
        "width": 10,
        "height": 10,
        "hazmat": {
          "transport_mode": "Ground",
          "emergency_phone": "8005551234",
          "emergency_contact": "Hazmat Response Team",
          "all_packed_in_one": true,
          "overpack": true,
          "q_value": "0.5",
          "chemical_records": [
            {
              "identifier": "1",
              "regulation_set": "CFR",
              "regulated_level_code": "FR",
              "id_number": "UN3480",
              "proper_shipping_name": "Lithium ion batteries",
              "technical_name": "Lithium Ion",
              "class_division_number": "9",
              "sub_risk_class": "4.1",
              "packaging_group": "II",
              "quantity": "6",
              "uom": "kg",
              "packaging_instruction_code": "965",
              "packaging_type": "Fiberboard Box",
              "packaging_type_quantity": "1",
              "hazard_label": "Y",
              "reportable_quantity": "RQ",
              "additional_description": "Limited Quantity",
              "transport_category": "0",
              "tunnel_restriction_code": "D/E"
            }
          ]
        }
      }
    ],
    "shipper": "RocketShipIt",
    "ship_addr1": "123 Main St",
    "ship_city": "Whitehall",
    "ship_state": "MT",
    "ship_code": "59759",
    "ship_phone": "1231231234",
    "ship_country": "US",
    "to_name": "John Doe",
    "to_addr1": "940 Presidio Ave",
    "to_addr2": "#103",
    "to_state": "CA",
    "to_city": "San Francisco",
    "to_code": "94115",
    "to_country": "US",
    "test": true
  }
}

The response will include rates with any applicable Dangerous Goods surcharges. You can inspect the rate_detail array on each rate to see itemized charges.

Multiple Chemical Records#

You can include up to 3 chemical records per package for UPS. Each record can have its own regulation_set — if omitted, it falls back to the top-level hazmat_regulation_set.

"chemical_records": [
  {
    "identifier": "1",
    "regulation_set": "CFR",
    "regulated_level_code": "FR",
    "id_number": "UN3480",
    "proper_shipping_name": "Lithium ion batteries",
    "class_division_number": "9",
    "quantity": "6",
    "uom": "kg",
    "packaging_instruction_code": "965",
    "packaging_type": "Fiberboard Box",
    "packaging_type_quantity": "1"
  },
  {
    "identifier": "2",
    "regulated_level_code": "LQ",
    "id_number": "UN1088",
    "proper_shipping_name": "Acetal",
    "class_division_number": "3",
    "packaging_group": "II",
    "quantity": "100",
    "uom": "ml",
    "packaging_instruction_code": "Y341",
    "packaging_type": "Fiberboard Box",
    "packaging_type_quantity": "1"
  }
]

Note that the second record does not set regulation_set — it will use the value from hazmat_regulation_set at the request level.