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:
| 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 |
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 |
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
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.
Updated 3 months ago