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.
Data collection requirement for DG item
When handling Dangerous Goods, it's crucial to collect specific data based on the type of UNID.
-
Always remember to collect the UNID and HTRC for all DG items ( Limited Quantity and Battery) :
- unitedNationsRegulatoryId: Must always be collected.
- transportationRegulatoryClass: Must always be collected.
-
For Limited Quantity (LQ) UNIDs Only (e.g., UN1120, UN1266):
- Packaging Group: Must be collected.
- Liquid Volume: Must be collected.
-
For Battery UNIDs Only (e.g., UN3481, UN3091):
- Packing Instruction: Must be collected.
Note: isHazmat parameter is mandatory for both Battery and LQ UNIDs. This helps in proper identification and handling of dangerous goods.
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:
| Name | Description | Required |
|---|---|---|
shipTo | The address where the shipment will be delivered. For Amazon orders, shipTo information is pulled directly from the Amazon order.Type: Address | Conditional |
shipFrom | The address where the package will be picked up. Type: Address | Yes |
returnTo | The address where the package will be returned if it cannot be delivered. Type: Address | No |
shipDate | The ship date and time (the requested pickup). This defaults to the current date and time. Type: string (date-time) | No |
shipperInstruction | This field describe shipper instruction Type: ShipperInstruction | No |
packages | A list of packages to be shipped and package details. Type: PackageList | Yes |
valueAddedServices | A collection of supported value-added services. Type: ValueAddedServiceDetails | No |
taxDetails | A list of tax detail information. Type: TaxDetailList | No |
channelDetails | Shipment source channel related information. Type: ChannelDetails | Yes |
clientReferenceDetails | Object to pass additional information about the MCI Integrator shipperType: List of ClientReferenceDetail Type: ClientReferenceDetails | No |
shipmentType | Object to pass shipment type Type: ShipmentType | No |
destinationAccessPointDetails | Object to pass Accesspoint id for counter delivery Type: DestinationAccessPointDetails | No |
Request header parameter
| Name | Description | Required |
|---|---|---|
x-amzn-shipping-business-id | Amazon shipping business to assume for this request. The default is AmazonShipping_UK.Type: enum ( X-amzn-shipping-business-id) | Yes |
x-amzn-access-token | Amazon shipping request token | Yes |
Response
A successful response includes the following:
| Name | Description | Schema |
|---|---|---|
payload | The 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
Marketplace: Amazon US for Off-Amazon
{
"shipTo": {
"name": "Test User",
"addressLine1": "Dearborn St",
"stateOrRegion": "Illinois",
"city": "Chicago",
"countryCode": "US",
"postalCode": "60601"
},
"shipFrom": {
"name": "Seattle W/H",
"addressLine1": "REITEN RD",
"city": "KENT",
"countryCode": "US",
"stateOrRegion": "WA",
"postalCode": "98030-6028"
},
"packages": [
{
"dimensions": {
"length": 10.0,
"width": 30.0,
"height": 20.0,
"unit": "CENTIMETER"
},
"weight": {
"unit": "GRAM",
"value": 1000.0
},
"insuredValue": {
"value": 1.0,
"unit": "USD"
},
"packageClientReferenceId": "TEST SHIPMENT - AO",
"items": [
{
"quantity": 1,
"isHazmat": true,
"dangerousGoodsDetails": {
"unitedNationsRegulatoryId": "UN2037",
"transportationRegulatoryClass": "2.2",
"packingGroup": "III"
},
"liquidVolume": {
"unit": "FL_OZ",
"value": 3.0
},
"weight": {
"value": 16.0,
"unit": "OUNCE"
}
}
]
}
],
"channelDetails": {
"channelType": "EXTERNAL"
}
}
{
"payload": {
"ineligibleRates": [],
"rates": [
{
"availableValueAddedServiceGroups": [],
"benefits": null,
"billedWeight": {
"unit": "POUND",
"value": 2
},
"carrierId": "AMZN_US",
"carrierName": "Amazon Shipping",
"paymentType": null,
"promise": {
"deliveryWindow": {
"end": "2024-08-15T03:00:00Z",
"start": "2024-08-15T03:00:00Z"
},
"pickupWindow": {
"end": "2024-08-10T00:00:00Z",
"start": "2024-08-09T21:30:00Z"
}
},
"rateId": "ca740c8669183b6520333523ff81db8752104b531e697f1be02ed7d770ee47bd1723213586113",
"rateItemList": null,
"requiresAdditionalInputs": false,
"serviceId": "std-us-swa-mfn",
"serviceName": "Amazon Shipping Ground",
"supportedDocumentSpecifications": [
{
"format": "PNG",
"printOptions": [
{
"supportedDPIs": [
300,
203
],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}
],
"supportedFileJoiningOptions": [
false
],
"supportedPageLayouts": [
"DEFAULT"
]
}
],
"size": {
"length": 6,
"unit": "INCH",
"width": 4
}
},
{
"format": "ZPL",
"printOptions": [
{
"supportedDPIs": [
300,
203
],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}
],
"supportedFileJoiningOptions": [
false
],
"supportedPageLayouts": [
"DEFAULT"
]
}
],
"size": {
"length": 6,
"unit": "INCH",
"width": 4
}
},
{
"format": "PDF",
"printOptions": [
{
"supportedDPIs": [
300,
203
],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}
],
"supportedFileJoiningOptions": [
false
],
"supportedPageLayouts": [
"DEFAULT"
]
}
],
"size": {
"length": 6,
"unit": "INCH",
"width": 4
}
}
],
"totalCharge": {
"unit": "USD",
"value": 11.27
}
}
],
"requestToken": "amzn1.rq.96902327498653.100"
}
}
Marketplace: Amazon UK for Off-Amazon
{
"shipTo": {
"name": "Customer Name",
"addressLine1": "12, Meersbrook Park Road",
"addressLine2": "Meersbrook",
"postalCode": "OXXX 6NA",
"city": "SHEFFIELD",
"stateOrRegion": "SHEFFIELD",
"countryCode": "GB",
"email": "Customer_Email@amazon.com",
"phoneNumber": "9999999999"
},
"shipFrom": {
"name": "Shipper Name",
"addressLine1": "Plane Tree Crescent",
"postalCode": "S8 XXP",
"city": "Feltham",
"stateOrRegion": "Feltham",
"countryCode": "GB",
"email": "Shipper_Email@amazon.com",
"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": "PI966_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"
}
}
{
"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": []
}
}
Marketplace: Amazon UK for On-Amazon
{
"shipTo": {
"name": "Test User",
"addressLine1": "12, Meersbrook Park Road",
"addressLine2": "Meersbrook",
"postalCode": "OX15 XXX",
"city": "SHEFFIELD",
"stateOrRegion": "SHEFFIELD",
"countryCode": "GB",
"email": "Customer_Email@amazon.com",
"phoneNumber": "9999999999"
},
"shipFrom": {
"name": "Test seller",
"addressLine1": "Plane Tree Crescent",
"postalCode": "SXX XXX",
"city": "Feltham",
"stateOrRegion": "Feltham",
"countryCode": "GB",
"email": "seller@amazon.com",
"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"
}
}
}
{
"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-b56605bc7.101"
}
}
Important: Review Dangerous Goods FAQ
Before proceeding with Dangerous Goods shipping, we highly recommend that you thoroughly review our Frequently Asked Questions (FAQs) section. This resource contains crucial information about eligibility, requirements, and best practices for shipping permissible dangerous goods with Amazon Shipping.
You can access the FAQs here: Dangerous Goods FAQs
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.
Updated 8 days ago
Did this page help you?