Dangerous Goods

Some carriers allow you to ship dangerous goods that would normally be restricted from mail, such as Lithium Ion Batteries. For any carrier that requires your shipping label to indicate that it contains hazardous materials, ShipEngine's Dangerous Goods object can help you!

Not all carriers will require or support all of the properties ShipEngine defines in our Dangerous Goods object. In general, we do advise that your integration allows entry of any field we have defined, since carrier support may vary. By sending full information, you ensure that your integration can ship Dangerous Goods with any carrier supported by ShipEngine.

ShipEngine supports many carriers, and we are adding new ones all the time. Some of our most popular carriers that support marking the shipment as Dangerous Goods include (but are not limited to) USPS and DHL eCommerce - US. To see if a specific carrier supports shipping Dangerous Goods, make a List Carrier Advanced Options call to learn at any point what advanced options that carrier supports. The Advanced Options page lists and describes what options you may see in the response to your call. You can also check the specific carrier guide.

Dangerous Goods Object

The following table lists all of the data points that describe the dangerous goods properties for the puposes of shipping.

Property	Type	Required or Optional	Description	Example
`id_number`	string	Optional	Standard 4-digit ID to identify the dangerous goods	UN1950
`shipping_name`	string	Optional	Trade description of the goods	Lithium metal batteries
`technical_name`	string	Optional	A widely recognized chemical or technical name.	Cyclotrimethylenetrinitramine, desensitized
`product_class`	string	Optional	"Substances (including mixtures and solutions) and articles are assigned to one of nine classes according to either the hazard, or the most prominent of the hazards, they present. Some of these classes are subdivided into divisions."	4.1
`product_class_subsidiary`	string	Optional	A secondary product class for substances presenting more than one particular hazard	2.2
`packaging_group`	enum	Optional	From the three packing groups that can be assigned to the substance, the one that indicates the degree of danger it presents	i, ii, …
`dangerous_amount`	number + string for unit of measure	Optional	The amount of the Dangerous material	0.2 kg
Quantity	number	Optional	Mathematical representation of the copies/pieces/volumes of the material being transported.	1
`package_instructions`	string	Optional	The specific standardized packaging instructions from the relevant regulatory agency that have been applied to the parcel/container.	P905 (UN recommendation used by ADR) 967 (IATA regulation)
`package_instruction_section`	enum	Optional	Complementary information to specify the exact 'Section of Packaging' Instructions (a mandatory piece of data for processing lithium batteries shipments)	I
`package_type`	string	Optional	The type of exterior package used to contain the regulated good	Fiberboard Box 1A1 (ADR)
`transport_mean`	enum	Optional	The most critical leg of the journey required to deliver the goods
`transport_category`	string	Optional	Category assigned to goods for the transport purpose	3
`regulation_authority`	string	Optional	Regulatory agency whose standards are being followed for the shipment, e.g. "ADR", "CFR", "IATA", "TDG".	IATA
`regulation_level`	enum	Optional	Reference to the amount of the substance being transported, used to trigger different levels of controls/restrictions	Fully Regulated lightly_regulated
radioactive	bool	Optional	An indication if the substance is radioactive	TRUE
`reportable_quantity`	bool	Optional	A flag to indicate whether or not the quantity of a hazardous substance from Title 40, Code of Federal Regulations (40 CFR) is sufficient to trigger a report under the Comprehensive Environmental Response, Compensation, and Liability Act (CERCLA)	TRUE
`tunnel_code`	string	Optional	Defines which types of tunnels the shipment is not allowed to go through	D

Example Request

POST /v1/labels

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "shipments": [
    {
      "validate_address": "no_validation",
      "service_code": "usps_priority_mail",
      "external_shipment_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",
      "ship_to": {
        "name": "Amanda Miller",
        "phone": "555-555-5555",
        "address_line1": "525 S Winchester Blvd",
        "city_locality": "San Jose",
        "state_province": "CA",
        "postal_code": "95128",
        "country_code": "US",
        "address_residential_indicator": "yes"
      },
      "ship_from": {
        "company_name": "Example Corp.",
        "name": "John Doe",
        "phone": "111-111-1111",
        "address_line1": "4009 Marathon Blvd",
        "address_line2": "Suite 300",
        "city_locality": "Austin",
        "state_province": "TX",
        "postal_code": "78756",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "confirmation": "none",
      "advanced_options": {
        "dangerous_goods_category": "06",
        "dangerous_goods": "true"
"dangerous_goods_contact":
{
"name": Ula
"phone": +48111111111
}
      },
      "insurance_provider": "none",
      "packages": [
        {
          "weight": {
            "value": 1,
            "unit": "ounce"
          },
    "products": [
            {
              "description": "laptop",
              "quantity": 1,
              "country_of_origin": "US",
              "sku": "121101",
              "dangerous_goods": [
                {

 "id_number": "UN3480",
                  "shipping_name": "lithium ion batteries",
                  "technical_name": "lithium iron phosphate",
                  "product_class": "4.2",
                  "packaging_group": "II",
                  "dangerous_amount": {
                    "value": 10,
                    "unit": "quart"
                  },
                  "quantity": 2,
                  "package_instructions": "903",
                  "package_instruction_section": "section_1B",
                  "package_type": "1A1",
                  "transport_mean": "ground",
                  "regulation_authority": "iata",
                  "regulation_level": "lightly_regulated",
                  "radioactive": false,
                  "reportable_quantity": false,
                  "tunnel_code": "D"

                }
              ]
            }
          ]
        }
      ],
      "total_weight": {
        "value": 1,
        "unit": "ounce"
      }
    }
  ]
}

Notice the advanced_options shown here as they appear in the request above:

1
2
3
4
5
6
7
8
9
10
11
{
  "advanced_options": {
      "dangerous_goods_category": "06"
      "dangerous_goods": "true"
      "dangerous_goods_contact":
      {
        "name": "Ula"
        "phone": "+4811111111"
      }
}
}

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
{
  "has_errors": false,
  "shipments": [
    {
      "errors": null,
      "address_validation": null,
      "shipment_id": "se-202902255",
      "carrier_id": "se-123890",
      "service_code": "usps_priority_mail",
      "external_shipment_id": "0bcb569d-1727-4ff9-ab49-b2fec0cee5ae",
      "ship_date": "2018-02-12T00:00:00Z",
      "created_at": "2018-02-13T00:53:52.0275877Z",
      "modified_at": "2018-02-13T00:53:52.0275877Z",
      "shipment_status": "pending",
      "ship_to": {
        "name": "Amanda Miller",
        "phone": "555-555-5555",
        "address_line1": "525 S Winchester Blvd",
        "city_locality": "San Jose",
        "state_province": "CA",
        "postal_code": "95128",
        "country_code": "US",
        "address_residential_indicator": "yes"
      },
      "ship_from": {
        "company_name": "Example Corp.",
        "name": "John Doe",
        "phone": "111-111-1111",
        "address_line1": "4009 Marathon Blvd",
        "address_line2": "Suite 300",
        "city_locality": "Austin",
        "state_province": "TX",
        "postal_code": "78756",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "warehouse_id": null,
      "return_to": {
        "company_name": "Example Corp.",
        "name": "John Doe",
        "phone": "111-111-1111",
        "address_line1": "4009 Marathon Blvd",
        "address_line2": "Suite 300",
        "city_locality": "Austin",
        "state_province": "TX",
        "postal_code": "78756",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "insurance_provider": "none",
      "tags": [],
      "packages": [
        {
          "weight": {
            "value": 1,
            "unit": "quart"
          },
          "products": [
            {
              "description": "laptop",
              "quantity": 1,
              "country_of_origin": "US",
              "sku": "121101",
              "dangerous_goods": [
                {
                  "un_number": "3480",
                  "shipping_name": "lithium ion batteries",
                  "technical_name": "lithium iron phosphate",
                  "product_class": "miscellaneous",
                  "packaging_group": "II",
                  "dangerous_amount": {
                    "value": 10,
                    "unit": "ounce"
                  },
                  "quantity": 2,
                  "package_instructions": "903",
                  "package_instruction_section": "section_1B",
                  "package_type": "1A1",
                  "transport_mean": "ground",
                  "regulation_authority": "iata",
                  "regulation_level": "lightly_regulated",
                  "radioactive": false,
                  "reportable_quantity": false,
                  "tunnel_code": "D"
                }
              ]
            }
          ]
        }
      ],
      "total_weight": {
        "value": 1,
        "unit": "ounce"
      }
    }
  ]
}