Tutorial: Purchase a Dangerous Goods Shipment for FRITES (France, Italy, Spain) marketplaces
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:
- Dangerous Goods (DG) enablement via Shipper Central.
(Navigate to Shipper Central / Dangerous Goods/ Declare dangerous goods / Accept the DG Addendum) - 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 Hazmat Transportation Regulatory Class (HTRC) for all DG items (Limited Quantity [LQ] and Battery):
- unitedNationsRegulatoryId (UNID): Must always be collected.
- transportationRegulatoryClass (HTRC): 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.
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 | Shipper-provided instructions for the carrier regarding package handling or delivery 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. Type: enum ( X-amzn-shipping-business-id) | No |
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_<CountryCode>
x-amz-access-token: Atza|IwEBIGorlXXX
API Request and Response examples for limited quantity item
Marketplace: Amazon IT for Off-Amazon
{
"shipTo": {
"name": "Test User",
"addressLine1": "Via dei Serragli 2",
"city": "Firenze",
"postalCode": "50100", //Sample postcodes for illustration
"countryCode": "IT",
},
"shipFrom": {
"name": "Shipper W/H",
"addressLine1": "Via Rigattieri 3",
"city": "Firenze",
"postalCode": "50123", //Sample postcodes for illustration
"countryCode": "IT",
"stateOrRegion": "PI",
},
"packages": [
{
"dimensions": {
"length": 10.0,
"width": 30.0,
"height": 20.0,
"unit": "CENTIMETER"
},
"weight": {
"unit": "GRAM",
"value": 1000.0
},
"insuredValue": {
"value": 1.0,
"unit": "EUR"
},
"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": 0.5,
"unit": "KILOGRAM"
}
}
]
}
],
"channelDetails": {
"channelType": "EXTERNAL"
}
}
{
"Output":
{
"__type": "com.amazon.shipping.api.gateway.v2#GetRatesOutput",
"ineligibleRates": [],
"rates": [
{
"__type": "com.amazon.shipping.api.model.v2#Rate",
"availableValueAddedServiceGroups": [],
"billedWeight":
{
"unit": "KILOGRAM",
"value": 10.0
},
"carrierId": "AMZN_IT",
"carrierName": "Amazon Shipping",
"promise":
{
"deliveryWindow":
{
"__type": "com.amazon.shipping.api.model#DateTimeRange",
"end": "2025-04-05T18:00:00Z",
"start": "2025-04-05T18:00:00Z"
},
"pickupWindow":
{
"__type": "com.amazon.shipping.api.model#DateTimeRange",
"end": "2025-04-04T17:00:00Z",
"start": "2025-04-04T12:30:00Z"
}
},
"rateId": "77f75e4066c5c9acccd052d4332507534b929c59ac2305aa77e3d0feb63bf5961743695293897",
"requiresAdditionalInputs": false,
"serviceId": "SWA-IT-PRIME-PREM",
"serviceName": "Spedizione nazionale express",
"supportedDocumentSpecifications": [
{
"format": "PNG",
"printOptions": [
{
"supportedDPIs": [300, 203],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}],
"supportedFileJoiningOptions": [false],
"supportedPageLayouts": ["DEFAULT"]
}],
"size":
{
"length": 6.0,
"unit": "INCH",
"width": 4.0
}
},
{
"format": "ZPL",
"printOptions": [
{
"supportedDPIs": [300, 203],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}],
"supportedFileJoiningOptions": [false],
"supportedPageLayouts": ["DEFAULT"]
}],
"size":
{
"length": 6.0,
"unit": "INCH",
"width": 4.0
}
},
{
"format": "PDF",
"printOptions": [
{
"supportedDPIs": [300, 203],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}],
"supportedFileJoiningOptions": [false],
"supportedPageLayouts": ["DEFAULT"]
}],
"size":
{
"length": 6.0,
"unit": "INCH",
"width": 4.0
}
}],
"totalCharge":
{
"__type": "com.amazon.Codigo#currency",
"unit": "EUR",
"value": 6.0
}
}],
"requestToken": "amzn1.rq.95305947486622.100"
},
"Version": "1.0"
}
API Request and Response examples for lithium ion battery
Marketplace: Amazon FR for Off-Amazon
{
"shipTo": {
"name": "Customer Name",
"addressLine1": "1 place de la Republique",
"city": "PARIS",
"postalCode": "75023", //Sample postcodes for illustration
"countryCode": "FR"
},
"shipFrom": {
"name": "Shipper Name",
"addressLine1": "40 quai de Jemmapes",
"city": "PARIS",
"postalCode": "75013", //Sample postcodes for illustration
"countryCode": "FR"
},
"packages": [
{
"dimensions": {
"length": 3.14,
"width": 3.14,
"height": 3.14,
"unit": "INCH"
},
"weight": {
"unit": "KILOGRAM",
"value": 2.4
},
"items": [
{
"quantity": 1,
"weight": {
"unit": "KILOGRAM",
"value": 1.20
},
"dangerousGoodsDetails": {
"unitedNationsRegulatoryId": "UN3481",
"transportationRegulatoryClass": "9",
"packingInstruction": "PI966_SECTION_II"
},
"isHazmat": true
},
{
"quantity": 1,
"weight": {
"unit": "KILOGRAM",
"value": 1.10
},
"dangerousGoodsDetails": {
"unitedNationsRegulatoryId": "UN3481",
"transportationRegulatoryClass": "9",
"packingInstruction": "PI966_SECTION_II"
},
"isHazmat": true
}
],
"insuredValue": {
"unit": "EUR",
"value": 29.98
},
"packageClientReferenceId": "<Use_Order_ID>"
}
],
"channelDetails": {
"channelType": "EXTERNAL"
}
}
{
"payload":
{
"ineligibleRates": [],
"rates": [
{
"availableValueAddedServiceGroups": [],
"billedWeight":
{
"unit": "KILOGRAM",
"value": 0.249
},
"carrierId": "AMZN_FR",
"carrierName": "Amazon Shipping",
"promise":
{
"deliveryWindow":
{
"end": "2025-04-08T18:00:00Z",
"start": "2025-04-08T18:00:00Z"
},
"pickupWindow":
{
"end": "2025-04-07T16:30:00Z",
"start": "2025-04-07T12:00:00Z"
}
},
"rateId": "d7e6d1fdbb6799a1c0bd16a1b415aff3b7d5cf47ee2f111eaa0affef0ccd38ab1743789021328",
"requiresAdditionalInputs": false,
"serviceId": "SWA-FR-PRIME-PREM",
"serviceName": "Amazon Shipping One Day",
"supportedDocumentSpecifications": [
{
"format": "PNG",
"printOptions": [
{
"supportedDPIs": [300, 203],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}],
"supportedFileJoiningOptions": [false],
"supportedPageLayouts": ["DEFAULT"]
}],
"size":
{
"length": 6.0,
"unit": "INCH",
"width": 4.0
}
},
{
"format": "ZPL",
"printOptions": [
{
"supportedDPIs": [300, 203],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}],
"supportedFileJoiningOptions": [false],
"supportedPageLayouts": ["DEFAULT"]
}],
"size":
{
"length": 6.0,
"unit": "INCH",
"width": 4.0
}
},
{
"format": "PDF",
"printOptions": [
{
"supportedDPIs": [300, 203],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}],
"supportedFileJoiningOptions": [false],
"supportedPageLayouts": ["DEFAULT"]
}],
"size":
{
"length": 6.0,
"unit": "INCH",
"width": 4.0
}
}],
"totalCharge":
{
"unit": "EUR",
"value": 10.63
}
}],
"requestToken": "amzn1.rq.93169622125085.100"
}
}
Marketplace: Amazon ES for Off-Amazon
{
"shipTo": {
"name": "Test User",
"addressLine1": "Calle 34",
"postalCode": "28011", //Sample postcodes for illustration
"city": "Madrid",
"countryCode": "ES",
"email": "[email protected]"
},
"shipFrom": {
"name": "Test seller",
"addressLine1": "C. de Ramírez de Prado, 5, Arganzuela",
"postalCode": "28001", //Sample postcodes for illustration
"city": "Madrid",
"stateOrRegion": "Spain",
"countryCode": "ES"
},
"packages": [
{
"dimensions": {
"length": 12.99,
"width": 9.45,
"height": 5.91,
"unit": "INCH"
},
"weight": {
"unit": "KILOGRAM",
"value": 0.4
},
"items": [
{
"itemValue": {
"unit": "EUR",
"value": 33.15
},
"description": "Lithium Ion Batteries",
"quantity": 1,
"weight": {
"unit": "KILOGRAM",
"value": 0.2
},
"dangerousGoodsDetails": {
"unitedNationsRegulatoryId": "UN3481",
"transportationRegulatoryClass": "9",
"packingInstruction": "PI966_SECTION_II"
},
"isHazmat": true
}
],
"insuredValue": {
"unit": "EUR",
"value": 33.15
},
"packageClientReferenceId": "SW17271398"
}
],
"channelDetails": {
"channelType": "EXTERNAL"
}
}
{
"payload":
{
"ineligibleRates": [],
"rates": [
{
"availableValueAddedServiceGroups": [],
"billedWeight":
{
"unit": "KILOGRAM",
"value": 0.249
},
"carrierId": "AMZN_ES",
"carrierName": "Amazon Shipping",
"promise":
{
"deliveryWindow":
{
"end": "2025-04-08T18:00:00Z",
"start": "2025-04-08T18:00:00Z"
},
"pickupWindow":
{
"end": "2025-04-07T15:45:00Z",
"start": "2025-04-07T12:00:00Z"
}
},
"rateId": "a84497dc503426e6bbe6fb0f3e60f319f384034805bbb111fbe6d6b52e9c4a9e1743790326414",
"requiresAdditionalInputs": false,
"serviceId": "SWA-ES-PRIME-PREM",
"serviceName": "Amazon Shipping express",
"supportedDocumentSpecifications": [
{
"format": "PNG",
"printOptions": [
{
"supportedDPIs": [300, 203],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}],
"supportedFileJoiningOptions": [false],
"supportedPageLayouts": ["DEFAULT"]
}],
"size":
{
"length": 6.0,
"unit": "INCH",
"width": 4.0
}
},
{
"format": "ZPL",
"printOptions": [
{
"supportedDPIs": [300, 203],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}],
"supportedFileJoiningOptions": [false],
"supportedPageLayouts": ["DEFAULT"]
}],
"size":
{
"length": 6.0,
"unit": "INCH",
"width": 4.0
}
},
{
"format": "PDF",
"printOptions": [
{
"supportedDPIs": [300, 203],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}],
"supportedFileJoiningOptions": [false],
"supportedPageLayouts": ["DEFAULT"]
}],
"size":
{
"length": 6.0,
"unit": "INCH",
"width": 4.0
}
}],
"totalCharge":
{
"unit": "EUR",
"value": 10.0
}
}],
"requestToken": "amzn1.rq.91328966256272.100"
}
}
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 4 days ago