Tutorial: Purchase a Limited Quantity Dangerous Goods Shipment From a Rate
How to get rates for a dangerous goods shipment that contains limited quantity 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. Refer to 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 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: At this time, 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 limited quantity item
Marketplace: Amazon UK for Off-Amazon
Get Rates API request with dangerous goods
{
"shipTo": {
"name": "Customer Name",
"addressLine1": "12, Meersbrook Park Road",
"addressLine2": "Meersbrook",
"postalCode": "OX15 XXX",
"city": "SHEFFIELD",
"stateOrRegion": "SHEFFIELD",
"countryCode": "GB",
"email": "[email protected]",
"phoneNumber": "9999999999"
},
"shipFrom": {
"name": "Shipper Name",
"addressLine1": "Plane Tree Crescent",
"postalCode": "S8 XXX",
"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": 0.44159
},
"liquidVolume": {
"unit": "ML",
"value": 100
},
"dangerousGoodsDetails": {
"unitedNationsRegulatoryId": "UN1170",
"transportationRegulatoryClass": "3",
"packingGroup": "II"
},
"isHazmat": true
},
{
"quantity": 1,
"weight": {
"unit": "KILOGRAM",
"value": 1.04159
},
"liquidVolume": {
"unit": "ML",
"value": "300"
},
"dangerousGoodsDetails": {
"unitedNationsRegulatoryId": "UN1170",
"transportationRegulatoryClass": "3",
"packingGroup": "II"
},
"isHazmat": true
}
],
"insuredValue": {
"unit": "GBP",
"value": 29.98
},
"packageClientReferenceId": "<Use_Order_ID>"
}
],
"channelDetails": {
"channelType": "EXTERNAL"
}
}
Get Rates API 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": []
}
}
Marketplace: Amazon US for Off-Amazon
Get Rates API request with dangerous goods
{
"shipTo": {
"name": "Test",
"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"
},
"shipDate": "2024-08-09T15:28:19Z",
"packages": [
{
"dimensions": {
"length": 5,
"width": 5,
"height": 5,
"unit": "INCH"
},
"weight": {
"value": 2,
"unit": "POUND"
},
"insuredValue": {
"value": 400,
"unit": "USD"
},
"isHazmat": true,
"sellerDisplayName": "SellerName",
"packageClientReferenceId": "9a29650d-6a09-4bbe-9e52-ee3cb50baac9-1",
"items": [
{
"itemValue": {
"value": 400,
"unit": "USD"
},
"description": "S1",
"quantity": 1,
"weight": {
"value": 2,
"unit": "POUND"
},
"isHazmat": true,
"dangerousGoodsDetails": {
"unitedNationsRegulatoryId": "UN3481",
"transportationRegulatoryClass": "9",
"packingInstruction": "PI966_SECTION_I"
}
}
]
}
],
"channelDetails": {
"channelType": "EXTERNAL"
}
}
Get Rates API response
{
"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 On-Amazon
Get Rates API 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 Basic Care - Aloe Vera Hand Sanitizer",
"itemIdentifier": "69783225326731",
"quantity": 1,
"weight": {
"unit": "KILOGRAM",
"value": 0.15
},
"liquidVolume": {
"unit": "ML",
"value": 200
},
"dangerousGoodsDetails": {
"unitedNationsRegulatoryId": "UN1170",
"transportationRegulatoryClass": "3",
"packingGroup": "II"
},
"isHazmat": true
}
],
"insuredValue": {
"unit": "GBP",
"value": 13.99
},
"packageClientReferenceId": "SW17271398"
}
],
"channelDetails": {
"channelType": "AMAZON",
"amazonOrderDetails": {
"orderId": "026-1671542-1523528"
}
}
}
Get Rates API 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"
}
}
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 2 days ago