Tutorial: Purchase a Dangerous Goods Shipment for an Item Containing a Lithium Ion Battery From a Rate

How to get rates for a dangerous goods shipment which contains lithium ion battery items, get any additional inputs when required, and purchase a dangerous goods shipment.

API Version: v2

Prerequisites

To complete this tutorial, you will need:

  • Enrollment in an eligible program.
  • A selling-partner account if you are an Amazon seller or are working with an Amazon seller to create and manage shipments.
  • Authorization from the selling partner for whom you are making calls. See the Authorizing Selling Partner API applications for more information.

Step 1. Get rates for a dangerous goods shipment

Getting the rates for a dangerous goods shipment returns the eligible shipping services for a given address, package specifications and/or pickup slot, and provides a delivery promise consisting of a pickup time range and a delivery window. If a pickup slot was not specified in the request by providing a shipDate value, the current date will be used to return the next eligible slot.

If you are fulfilling an Amazon order, The Amazon order number must be provided in the channel details in the getRates request.

Amazon Order example:

"channelDetails": {
  "channelType": "AMAZON",
  "amazonOrderDetails": {
    "orderId": "912-1061508-5843035"
  }
}

The Order Item ID should be sent in the itemIdentifier attribute. Use the getOrder or getOrderItems operation to fetch the order item.

Note: Each dangerous goods shipment is limited to a single package. Packages are always input, stored, and output in list form. You should write your API integration to work with lists of packages. This will keep your integration forward-compatible with multi-package shipments should the single package limitation be removed.

Request

To get the rates for a shipment, call the getRates operation, passing the following parameters:

NameDescriptionRequired
shipToThe address where the shipment will be delivered. For Amazon orders, shipTo information is pulled directly from the Amazon order.
Type: Address
Conditional
shipFromThe address where the package will be picked up.
Type: Address
Yes
returnToThe address where the package will be returned if it cannot be delivered.
Type: Address
No
shipDateThe ship date and time (the requested pickup). This defaults to the current date and time.
Type: string (date-time)
No
packagesA list of packages to be shipped and package details.
Type: PackageList
Yes
valueAddedServicesA collection of supported value-added services.
Type: ValueAddedServiceDetails
No
taxDetailsA list of tax detail information.
Type: TaxDetailList
No
channelDetailsShipment source channel related information.
Type: ChannelDetails
Yes

Request header parameter

NameDescriptionRequired
x-amzn-shipping-business-idAmazon shipping business to assume for this request. The default is AmazonShipping_UK.
Type: enum (X-amzn-shipping-business-id)
Yes
x-amzn-access-tokenAmazon shipping request tokenYes

Response

A successful response includes the following:

NameDescriptionSchema
payloadThe payload for the getRates operation.GetRatesResult

Sample API Request

POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/rates
x-amzn-shipping-business-id: AmazonShipping_UK
x-amz-access-token: Atza|IwEBIGorlXXX

API Request and Response examples for lithium ion battery

Off-Amazon request with dangerous goods
{
  "shipTo": {
    "name": "Customer Name",
    "addressLine1": "12, Meersbrook Park Road",
    "addressLine2": "Meersbrook",
    "postalCode": "OX15 6NA",
    "city": "SHEFFIELD",
    "stateOrRegion": "SHEFFIELD",
    "countryCode": "GB",
    "email": "[email protected]",
    "phoneNumber": "9999999999"
  },
  "shipFrom": {
    "name": "Shipper Name",
    "addressLine1": "Plane Tree Crescent",
    "postalCode": "S8 9FP",
    "city": "Feltham",
    "stateOrRegion": "Feltham",
    "countryCode": "GB",
    "email": "[email protected]",
    "phoneNumber": "9999999999"
  },
  "shipDate": "2022-03-23T09:00:00Z",
  "packages": [
    {
      "dimensions": {
        "length": 3.14,
        "width": 3.14,
        "height": 3.14,
        "unit": "INCH"
      },
      "weight": {
        "unit": "KILOGRAM",
        "value": 3.14159
      },
      "items": [
        {
          "quantity": 1,
          "weight": {
            "unit": "KILOGRAM",
            "value": 1.14159
          },
          "dangerousGoodsDetails": {
            "unitedNationsRegulatoryId": "UN3481",
            "transportationRegulatoryClass": "9",            
            "packingInstruction": "PI965_SECTION_II"
          },
          "isHazmat": true
        },
        {
          "quantity": 1,
          "weight": {
            "unit": "KILOGRAM",
            "value": 1.14159
          },
          "dangerousGoodsDetails": {
            "unitedNationsRegulatoryId": "UN3481",
            "transportationRegulatoryClass": "9",            
            "packingInstruction": "PI966_SECTION_II"
          },
          "isHazmat": true
        }
      ],
      "insuredValue": {
        "unit": "GBP",
        "value": 29.98
      },
      "packageClientReferenceId": "<Use_Order_ID>"
    }
  ],
  "channelDetails": {
    "channelType": "EXTERNAL"
  }
}
Off-Amazon response
{
  "payload": {
    "requestToken": "amzn1.94b6c96d-68ab-4fe6-a278-b85835b7e475",
    "rates": [
      {
        "rateId": "e1b7cf2d1516d8c5343a087e10a5a2261ff36b83bdb5a91c6ce51b19586ed9861507200580943",
        "carrierId": "AMZN_UK",
        "carrierName": "Amazon Shipping",
        "serviceId": "SWA-UK-PRIME-PREM",
        "serviceName": "Amazon Shipping One Day",
        "promise": {
          "pickupWindow": {
            "startTime": "2017-10-13T19:51:23Z",
            "endTime": "2017-10-13T19:51:23Z"
          },
          "deliveryWindow": {
            "startTime": "2017-10-14T19:51:23Z",
            "endTime": "2017-10-14T19:51:23Z"
          }
        },
        "supportedDocumentSpecifications": [
          {
            "format": "PNG",
            "size": {
              "width": 4,
              "length": 6,
              "unit": "INCH"
            },
            "printOptions": [
              {
                "supportedDPIs": [
                  300,
                  203
                ],
                "supportedPageLayouts": [
                  "DEFAULT"
                ],
                "supportedFileJoiningOptions": [
                  false
                ],
                "supportedDocumentDetails": [
                  {
                    "name": "LABEL",
                    "isMandatory": true
                  }
                ]
              }
            ]
          },
          {
            "format": "ZPL",
            "size": {
              "width": 4,
              "length": 6,
              "unit": "INCH"
            },
            "printOptions": [
              {
                "supportedDPIs": [
                  300,
                  203
                ],
                "supportedPageLayouts": [
                  "DEFAULT"
                ],
                "supportedFileJoiningOptions": [
                  false
                ],
                "supportedDocumentDetails": [
                  {
                    "name": "LABEL",
                    "isMandatory": true
                  }
                ]
              }
            ]
          },
          {
            "format": "PDF",
            "size": {
              "width": 4,
              "length": 6,
              "unit": "INCH"
            },
            "printOptions": [
              {
                "supportedDPIs": [
                  300,
                  203
                ],
                "supportedPageLayouts": [
                  "DEFAULT"
                ],
                "supportedFileJoiningOptions": [
                  false
                ],
                "supportedDocumentDetails": [
                  {
                    "name": "LABEL",
                    "isMandatory": true
                  }
                ]
              }
            ]
          }
        ],
        "availableValueAddedServiceGroups": null,
        "totalCharge": {
          "unit": "GBP",
          "value": 4.76
        },
        "billedWeight": {
          "value": 1,
          "unit": "KILOGRAM"
        },
        "requiresAdditionalInputs": false
      },
      {
        "rateId": "e9305a93989acce639f625842b64708f9daaf73bb87cc0cbf11f31f3c944b9761507200580943",
        "carrierId": "AMZN_UK",
        "carrierName": "Amazon Shipping",
        "serviceId": "SWA-UK-ECON",
        "serviceName": "Amazon Shipping Standard",
        "promise": {
          "pickupWindow": {
            "startTime": "2017-10-13T19:51:23Z",
            "endTime": "2017-10-13T23:51:23Z"
          },
          "deliveryWindow": {
            "startTime": "2017-10-18T19:51:23Z",
            "endTime": "2017-10-18T19:51:23Z"
          }
        },
        "supportedDocumentSpecifications": [
          {
            "format": "PNG",
            "size": {
              "width": 4,
              "length": 6,
              "unit": "INCH"
            },
            "printOptions": [
              {
                "supportedDPIs": [
                  300,
                  203
                ],
                "supportedPageLayouts": [
                  "DEFAULT"
                ],
                "supportedFileJoiningOptions": [
                  false
                ],
                "supportedDocumentDetails": [
                  {
                    "name": "LABEL",
                    "isMandatory": true
                  }
                ]
              }
            ]
          },
          {
            "format": "ZPL",
            "size": {
              "width": 4,
              "length": 6,
              "unit": "INCH"
            },
            "printOptions": [
              {
                "supportedDPIs": [
                  300,
                  203
                ],
                "supportedPageLayouts": [
                  "DEFAULT"
                ],
                "supportedFileJoiningOptions": [
                  false
                ],
                "supportedDocumentDetails": [
                  {
                    "name": "LABEL",
                    "isMandatory": true
                  }
                ]
              }
            ]
          },
          {
            "format": "PDF",
            "size": {
              "width": 4,
              "length": 6,
              "unit": "INCH"
            },
            "printOptions": [
              {
                "supportedDPIs": [
                  300,
                  203
                ],
                "supportedPageLayouts": [
                  "DEFAULT"
                ],
                "supportedFileJoiningOptions": [
                  false
                ],
                "supportedDocumentDetails": [
                  {
                    "name": "LABEL",
                    "isMandatory": true
                  }
                ]
              }
            ]
          }
        ],
        "availableValueAddedServiceGroups": null,
        "totalCharge": {
          "unit": "GBP",
          "value": 3.72
        },
        "billedWeight": {
          "value": 1,
          "unit": "KILOGRAM"
        },
        "requiresAdditionalInputs": false
      }
    ],
    "ineligibleRates": []
  }
}
On-Amazon request with dangerous goods
{
  "shipTo": {
    "name": "James Martin - New Country Company",
    "addressLine1": "12, Meersbrook Park Road",
    "addressLine2": "Meersbrook",
    "postalCode": "OX15 6NA",
    "city": "SHEFFIELD",
    "stateOrRegion": "SHEFFIELD",
    "countryCode": "GB",
    "email": "[email protected]",
    "phoneNumber": "9999999999"
  },
  "shipFrom": {
    "name": "A1",
    "addressLine1": "Plane Tree Crescent",
    "postalCode": "S8 9FP",
    "city": "Feltham",
    "stateOrRegion": "Feltham",
    "countryCode": "GB",
    "email": "[email protected]",
    "phoneNumber": "9999999999"
  },
  "packages": [
    {
      "dimensions": {
        "length": 12.99,
        "width": 9.45,
        "height": 5.91,
        "unit": "INCH"
      },
      "weight": {
        "unit": "KILOGRAM",
        "value": 0.5
      },
      "items": [
        {
          "itemValue": {
            "unit": "GBP",
            "value": 13.99
          },
          "description": "Amazon Basics 3-Pack Rechargeable AA NiMH Batteries",
          "itemIdentifier": "69783225326731",
          "quantity": 1,
          "weight": {
            "unit": "KILOGRAM",
            "value": 0.01
          },
          "dangerousGoodsDetails": {
            "unitedNationsRegulatoryId": "UN3481",
            "transportationRegulatoryClass": "9",            
            "packingInstruction": "PI966_SECTION_II"
          },
          "isHazmat": true
        }
      ],
      "insuredValue": {
        "unit": "GBP",
        "value": 13.99
      },
      "packageClientReferenceId": "SW17271398"
    }
  ],
  "channelDetails": {
    "channelType": "AMAZON",
    "amazonOrderDetails": {
      "orderId": "026-1671542-1523528"
    }
  }
}
On-Amazon response
{
  "payload": {
    "ineligibleRates": [
      {
        "carrierId": "CHINA_POST",
        "carrierName": "China Post",
        "ineligibilityReasons": [
          {
            "code": "UNKNOWN",
            "message": "It is not an eligible ship method for this order."
          },
          {
            "code": "UNKNOWN",
            "message": "The Carrier Terms and Conditions were not accepted"
          }
        ],
        "serviceId": "CHINA_POST_AIRMAIL",
        "serviceName": "China Post Ordinary Airmail"
      }
    ],
    "rates": [
      {
        "availableValueAddedServiceGroups": [
          {
            "groupDescription": "Pickup",
            "groupId": "VAS_GROUP_ID_PICKUP",
            "isRequired": true,
            "valueAddedServices": [
              {
                "cost": {
                  "unit": "GBP",
                  "value": 0
                },
                "id": "CARRIER_PICKUP_CHARGE",
                "name": "Carrier Pickup"
              }
            ]
          }
        ],
        "carrierId": "AMZN_UK",
        "carrierName": "Amazon Shipping",
        "promise": {
          "deliveryWindow": {
            "endTime": "2021-10-20T19:00:00Z",
            "startTime": "2021-10-20T19:00:00Z"
          },
          "pickupWindow": {
            "endTime": "2021-10-18T17:30:00Z",
            "startTime": "2021-10-18T17:00:00Z"
          }
        },
        "rateId": "0193bfed-6bc1-449c-8504-02a431732d55",
        "requiresAdditionalInputs": false,
        "serviceId": "prime-premium-uk-mfn",
        "serviceName": "Amazon Shipping One-Day Tracked",
        "supportedDocumentSpecifications": [
          {
            "format": "PNG",
            "printOptions": [
              {
                "supportedDPIs": [],
                "supportedDocumentDetails": [
                  {
                    "isMandatory": true,
                    "name": "LABEL"
                  }
                ],
                "supportedFileJoiningOptions": [
                  true
                ],
                "supportedPageLayouts": [
                  "LEFT"
                ]
              }
            ],
            "size": {
              "length": 6,
              "unit": "INCH",
              "width": 4
            }
          },
          {
            "format": "ZPL",
            "printOptions": [
              {
                "supportedDPIs": [
                  300
                ],
                "supportedDocumentDetails": [
                  {
                    "isMandatory": true,
                    "name": "LABEL"
                  }
                ],
                "supportedFileJoiningOptions": [
                  true
                ],
                "supportedPageLayouts": [
                  "LEFT"
                ]
              }
            ],
            "size": {
              "length": 6,
              "unit": "INCH",
              "width": 4
            }
          }
        ],
        "totalCharge": {
          "unit": "GBP",
          "value": 2.53
        }
      }
    ],
    "requestToken": "amzn1.rq.e15983c1-3ab7-40b5-bd9f-46cb56605bc7.101"
  }
}

Step 2. Discover required additional inputs for a shipment

Refer to Discover required additional inputs for a shipment.

Step 3. Purchase a shipment

Refer to Purchase a shipment.