Creating Dangerous Goods Consignments via the MachShip API

Overview

Welcome to the guide on creating dangerous goods (DG) consignments using the MachShip API. This document serves as a companion to our main guide on Creating Consignments and focuses specifically on the additional considerations and steps required when shipping dangerous goods.

Understanding DG Consignments

Dangerous goods consignments are shipments that contain hazardous items requiring special care during transportation. It's crucial to fully declare all information related to the dangerous goods being sent to ensure compliance with local regulations.

In the context of MachShip, a dangerous goods consignment includes all the standard consignment information (pick-up location, delivery location, items) plus additional details specific to the hazardous nature of the goods.

Key Differences for DG Consignments

When creating a DG consignment via the MachShip API, there are several key differences compared to standard consignments:

  1. API Endpoint: You'll use the /apiv2/consignments/createConsignmentwithComplexItems endpoint instead of the standard consignment creation endpoint. This endpoint is not limited for use with DG consignments and can be used to create any consignment.
  2. DG Declaration: You must explicitly declare that the consignment contains dangerous goods.
  3. Item Details: More detailed information about the dangerous goods is required.
  4. Carrier Restrictions: Not all carriers or services support dangerous goods shipments.

Creating DG Consignments

The process of creating a DG consignment is similar to creating a standard consignment, with some additional steps and parameters. We'll focus on the DG-specific aspects here.

For details on the remaining fields, please see our Creating Consignments guide.

Request Preparation

When preparing your request to the /apiv2/consignments/createConsignmentwithComplexItems endpoint for a DG consignment, you'll need to include additional information beyond what's required for standard consignments.

Dangerous Goods Declaration

This is a required field for all consignments when a company has Dangerous Goods enabled. You must set this to true for DG consignments:

{
  "dgsDeclaration": true
}

Items with Dangerous Goods Information

For items that are classified as dangerous goods, you need to provide detailed information through the consignmentItemDgItems object:

{
  "items": [
    {
      "itemType": "Carton",
      "name": "Test Carton",
      "sku": "CART",
      "quantity": 1,
      "standardItem": {
        "height": 25,
        "weight": 5,
        "length": 20,
        "width": 20
      },
      "consignmentItemDgItems": [
        {
          "unNumber": 1263,
          "packingGroup": 3,
          "containerType": 1,
          "aggregateQuantity": 20,
          "isAggregateQuantityWeight": false,
          "numberOfContainers": 1,
          "isMarinePollutant": true,
          "isTemperatureControlled": false,
          "dgClassType": 5
        }
      ]
    }
  ]
}

Let's break down the consignmentItemDgItems object:

  • unNumber (required). This will be the United Nations Number which represents the global identifier for that dangerous goods product
  • Packing Group (required). MachShip will require you to provide one of the enums below based on the pack group that represents the product being sent
    • 1 - Pack Group 1
    • 2 - Pack Group 2
    • 3 - Pack Group 3
    • 4 - Pack Group N/A
    • Note, the above values are enums - this means if you wanted to set a packing group of N/A you would set "4". If you wanted packing group 2 - you would send "2".
  • Container Type (required). enum for the container type for the DG. Needs to be one of the below:
    • 1 - Drum
    • 2 - Carton
    • 3 - IBC
    • 4 - Pail
    • 5 - Demountable Tank
    • 6 - Bottle
    • 7 - Pressure Drum
    • 8 - Tube
    • 9 - MEGC
    • 10 - Aerosol
    • 11 - Bag
    • Note, the above values are enums - this means if you wanted to set a container type of IBC you would set "3". If you wanted container type of carton - you would send "2".
  • Aggregate Quantity (required). The amount of this DG that you are sending. For example, if you were sending 5 kg, you would send through 5. If you're sending 2 litres, it would be 2.
  • isAggregateQuantityWeight (required). This will be either true or false based on if the aggregate quantity amount provided is in kilos (true) or litres (false).
  • numberofContainers (required). The number of containers which contain dangerous goods
  • isMarinePollutant (required). Either true or false based on if the dangerous goods item is a marine pollutant or not
  • isTemperatureControlled (required). Either true or false based on if the dangerous goods item requires being temperature controlled or not.
  • isEmptyDgContainer (required). Either true or false based on if the dangerous goods item is an empty uncleaned container or not
  • dgClassType. (optional) enum which advises the primary class of the DG
    • 1 - Class 1 Explosive (cannot be consigned in MachShip)
    • 2 - Class 2.1 Flammable Gas
    • 3 - Class 2.2 Other Gas
    • 4 - Class 2.3 Toxic Gas
    • 5 - Class 3 Flammable Liquid
    • 6 - Class 4.1 Flammable Solid
    • 7 - Class 4.2 Spontaneously Combustible
    • 8 - Class 4.3 Dangerous When Wet
    • 9 - Class 5.1 Oxidising Agent
    • 10 - Class 5.2 Organic Peroxide
    • 11 - Class 6.1 Toxic Substance
    • 12 - Class 6.2 Infections Substance
    • 13 - Class 7 Radioactive (Cannot be consigned in MachShip)
    • 14 - Class 8 Corrosive
    • 15 - Class 9 - Miscellaneous
    • Note, the above values are enums - this means if you wanted to set a dgClassType of 5.1 you would set "9". If you wanted dgClassType of 8 - you would set "14"
  • subDgClassTypes (optional). An array of enum's which advice on all of the secondary classes of the DG
    • 1 - Class 1 Explosive (cannot be consigned in MachShip)
    • 2 - Class 2.1 Flammable Gas
    • 3 - Class 2.2 Other Gas
    • 4 - Class 2.3 Toxic Gas
    • 5 - Class 3 Flammable Liquid
    • 6 - Class 4.1 Flammable Solid
    • 7 - Class 4.2 Spontaneously Combustible
    • 8 - Class 4.3 Dangerous When Wet
    • 9 - Class 5.1 Oxidising Agent
    • 10 - Class 5.2 Organic Peroxide
    • 11 - Class 6.1 Toxic Substance
    • 12 - Class 6.2 Infections Substance
    • 13 - Class 7 Radioactive (Cannot be consigned in MachShip)
    • 14 - Class 8 Corrosive
    • 15 - Class 9 - Miscellaneous
    • Note, the above values are enums - this means if you wanted to set a subDgClassTypes of 5.1 you would set "9". If you wanted subDgClassTypes of 8 - you would set "14"

Send Your Request

Once you've prepared all the necessary information, including the DG-specific details, you're ready to send your request. Here's an example of what a complete request for a DG consignment might look like:

POST https://live.machship.com/apiv2/consignments/createConsignmentwithComplexItems HTTP/1.1
Host: live.machship.com
token: <api_token>
body:
{
  "dgsDeclaration": true,
  "items": [
    {
      "itemType": "Carton",
      "name": "Test Carton",
      "sku": "CART",
      "quantity": 1,
      "standardItem": {
        "height": 25,
        "weight": 5,
        "length": 20,
        "width": 20
      },
      "consignmentItemDgItems": [
        {
          "unNumber": 1263,
          "packingGroup": 3,
          "containerType": 1,
          "aggregateQuantity": 20,
          "isAggregateQuantityWeight": false,
          "numberOfContainers": 1,
          "isMarinePollutant": true,
          "isTemperatureControlled": false,
          "dgClassType": 5
        }
      ]
    }
  ],
  "carrierId": 11,
  "carrierServiceId": 123,
  "carrierAccountId": 456,
  "companyCarrierAccountId": 789,
  "fromName": "Chemical Warehouse",
  "fromContact": "John Doe",
  "fromPhone": "1234567890",
  "fromEmail": "john@chemicalwarehouse.com",
  "fromAddressLine1": "123 Industrial St",
  "fromLocation": {
    "suburb": "Melbourne",
    "postcode": "3000"
  },
  "toName": "Research Lab",
  "toContact": "Jane Smith",
  "toPhone": "9876543210",
  "toEmail": "jane@researchlab.com",
  "toAddressLine1": "456 Science Ave",
  "toLocation": {
    "suburb": "Sydney",
    "postcode": "2000"
  },
  "specialInstructions": "Handle with care - Flammable"
}

Response Handling

The response for a DG consignment includes:

  • id: Unique identifier for the consignment
  • carrierConsignmentId: Carrier's reference
  • status: Usually "Unmanifested" for new consignments
  • consignmentTotal: Breakdown of pricing and surcharges
  • items: Detailed item information

Error Handling

Common DG-specific errors include:

  1. "Dangerous Goods / No Dangerous Goods must be declared": Missing dgsDeclaration field
  2. "Route is not Dangerous Goods route yet Dangerous Goods have been declared": Carrier/service doesn't support DG
  3. Invalid UN Number or Packing Group: Incorrect dangerous goods details

For more information on handling API errors, refer to our Common API Errors guide.

Summary

Creating DG consignments requires:

  1. Using the correct API endpoint
  2. Declaring dangerous goods presence
  3. Providing detailed DG item information
  4. Selecting DG-compatible carriers and services

Always prioritize safety when shipping dangerous goods. When in doubt, consult shipping experts or regulatory authorities.