> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.goshippo.com/feedback
```json
{
"path": "/docs/Carriers/DHLeCommerce",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# DHL eCommerce
> Connect your DHL eCommerce account to Shippo and learn how to get rates and purchase shipping labels.
DHL eCommerce is an ideal carrier for third-party logistics businesses offering preferential rates for high-volume shippers.
Follow this guide to learn how to use your own DHL eCommerce account with Shippo.
**note**
Before beginning this guide, you must have your own [DHL eCommerce account](https://www.dhl.com/global-en/home/our-divisions/ecommerce.html).
Contact your DHL eCommerce account manager to get the [required parameters](/docs/Carriers/CarrierCapabilities#dhl-ecommerce) to connect your account to Shippo.
## Get a label from DHL eCommerce
### 1. Connect your account
Before you can get rates from DHL eCommerce, you must first add your [account details](/docs/Carriers/CarrierAccounts#dhl-ecommerce).
**Request:**
```shell Connect your DHL eCommerce account theme={null}
curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken ' \
--header 'Content-Type: application/json' \
--data-raw '{
"account_id": "string",
"active": true,
"carrier": "dhl_ecommerce",
"account_id": "dhl_ecommerce",
"parameters": {
"username": "HipposDontLie!", // DHL eCommerce client ID
"password": "shipshippo", // DHL eCommerce client secret
"pickup_no": "123123", // DHL eCommerce pickup number
"facility_code": "23" // DHL eCommerce facility code
}
"test": false
}'
```
**Response:**
```json Connect your DHL eCommerce account response theme={null}
{
"account_id": "****",
"active": true,
"carrier": "dhl_ecommerce",
"parameters": {
"username": "HipposDontLie!", // DHL eCommerce client ID
"password": "shipshippo", // DHL eCommerce client secret
"pickup_no": "123123", // DHL eCommerce pickup number
"facility_code": "23" // DHL eCommerce facility code
},
"is_shippo_account": false,
"metadata": "string",
"object_id": "3579ad96a9534ea2bcc3487e703c98a1",
"object_owner": "mrhippo@goshippo.com",
"test": false
}
```
### 2. Get a rate from carrier
To get rates from your preferred carrier only, create a Shipment and use `carrier_accounts` with the object ID of your carrier.
The following example uses the object ID of the carrier added in [step 1](#1-connect-your-account).
**note**
For international shipments, DHL eCommerces will not return a rate while in [test mode](/docs/Guides_general/testing). To get a rate, ensure you are using a live token and your carrier is not in test mode.
**Request:**
```shell Get rates request theme={null}
curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken ' \
--header 'Content-Type: application/json' \
--data-raw '{
"address_from": {
"name": "Mr Hippo",
"street1": "965 Mission Street",
"street2": "Suite 480",
"city": "San Francisco",
"state": "CA",
"zip": "94103",
"country": "US",
"phone": "4151234567",
"email": "mrhippo@goshippo.com"
},
"address_to": {
"name": "Mr Hippo",
"street1": "2967 Filbert Dr",
"street2": "APT 3",
"city": "Walnut Creek",
"state": "CA",
"zip": "94598",
"country": "US",
"phone": "4151234567",
"email": "mrhippo@goshippo.com"
},
"parcels": [{
"weight": "8",
"length": "9",
"width": "3",
"height": "8",
"distance_unit": "in",
"mass_unit": "lb"
}],
"extra": {
"signature_required": "DIRECT"
},
"async": false,
"carrier_accounts":["3579ad96a9534ea2bcc3487e703c98a1"]
}'
```
**Response:**
```json Get rates response theme={null}
{
"carrier_accounts": [
"3579ad96a9534ea2bcc3487e703c98a1"
],
"object_created": "2024-02-09T15:51:51.386Z",
"object_updated": "2024-02-09T15:51:51.386Z",
"object_id": "ae70f937c08c45c59a0554dee6797270",
"object_owner": "adrian.collins@goshippo.com",
"status": "SUCCESS",
"address_from": {
"object_id": "3f45f9e843834fcb9417d120f3a76943",
"is_complete": true,
"name": "Mr Hippo",
"company": "",
"street_no": "",
"street1": "965 Mission Street",
"validation_results": {},
"street2": "Suite 480",
"street3": "",
"city": "San Francisco",
"state": "CA",
"zip": "94103",
"country": "US",
"phone": "4151234567",
"email": "mrhippo@goshippo.com",
"is_residential": null,
"test": true
},
"address_to": {
"object_id": "886aac005c1a4abcb02c401c4f298d5b",
"is_complete": true,
"name": "Mr Hippo",
"company": "",
"street_no": "",
"street1": "2967 Filbert Dr",
"validation_results": {},
"street2": "APT 3",
"street3": "",
"city": "Walnut Creek",
"state": "CA",
"zip": "94598",
"country": "US",
"phone": "4151234567",
"email": "mrhippo@goshippo.com",
"is_residential": null,
"test": true
},
"parcels": [
{
"object_state": "VALID",
"object_created": "2024-02-09T15:51:51.340Z",
"object_updated": "2024-02-09T15:51:51.397Z",
"object_id": "0042019fad6a4a53ace731142a568048",
"object_owner": "adrian.collins@goshippo.com",
"template": null,
"extra": {},
"length": "9.0000",
"width": "8.0000",
"height": "3.0000",
"distance_unit": "in",
"weight": "8.0000",
"mass_unit": "lb",
"value_amount": null,
"value_currency": null,
"metadata": "",
"line_items": [],
"test": true
}
],
"shipment_date": "2024-02-09T15:51:51.340Z",
"address_return": {
"object_id": "3f45f9e843834fcb9417d120f3a76943",
"is_complete": true,
"name": "Mr Hippo",
"company": "",
"street_no": "",
"street1": "965 Mission Street",
"validation_results": {},
"street2": "Suite 480",
"street3": "",
"city": "San Francisco",
"state": "CA",
"zip": "94103",
"country": "US",
"phone": "4151234567",
"email": "mrhippo@goshippo.com",
"is_residential": null,
"test": true
},
"customs_declaration": null,
"extra": {
"signature_required": "DIRECT"
},
"rates": [
{
"object_created": "2024-02-09T15:51:52.407Z",
"object_id": "b94689b62e8c4fda9e37fd8d61c8ebd4",
"object_owner": "adrian.collins@goshippo.com",
"shipment": "ae70f937c08c45c59a0554dee6797270",
"attributes": [
"BESTVALUE",
"CHEAPEST"
],
"amount": "13.17",
"currency": "USD",
"amount_local": "13.17",
"currency_local": "USD",
"provider": "DHL eCommerce",
"provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/DHL_ecommerce.png",
"provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/DHL_ecommerce.png",
"servicelevel": {
"name": "Parcels Ground",
"token": "dhl_ecommerce_parcels_ground",
"terms": ""
},
"estimated_days": 5,
"arrives_by": null,
"duration_terms": "",
"messages": [],
"carrier_account": "3579ad96a9534ea2bcc3487e703c98a1",
"test": true,
"zone": "USPS08"
}
],
"messages": [],
"metadata": "",
"test": true,
"order": null
}
},
```
### 3. Purchase label
To purchase a label, create a Transaction using the object ID of your preferred Rate.
**Request:**
```shell Purchase label theme={null}
curl --location 'https://api.goshippo.com/transactions/' \
--header 'Authorization: ShippoToken ' \
--header 'Content-Type: application/json' \
--data '{
"rate": "b94689b62e8c4fda9e37fd8d61c8ebd4",
"async": false
}'
```
**Response:**
```json Purchase label response theme={null}
{
"object_state": "VALID",
"status": "SUCCESS",
"object_created": "2024-02-09T15:54:15.760Z",
"object_updated": "2024-02-09T15:54:17.003Z",
"object_id": "162b77609c574d499daa9c63d813a845",
"object_owner": "adrian.collins@goshippo.com",
"test": true,
"rate": "b94689b62e8c4fda9e37fd8d61c8ebd4",
"tracking_number": "420945989261299999999900348426",
"tracking_status": "UNKNOWN",
"eta": null,
"tracking_url_provider": "https://webtrack.dhlglobalmail.com/?trackingnumber=420945989261299999999900348426",
"label_url": "https://deliver.goshippo.com/162b77609c574d499daa9c63d813a845.pdf?Expires=1739030056&Signature=Qzu1k~x5dVgmJqX89t1~EjB4p6jeuorKluEaWLh3mBfpz4OesKeugBBw4KywxNdcA6IPNPQcygEtf8AHdQjWt8MBIintLYBRTy0d7cBZNiiw5NOAGvAu5bfG0etnfC9C0alow2DdxJAhs7UhaemIo4~zWBP2nbQmssycaYwcDAGMHqQjBwjEd5-qTpGf0~Xs1az-xFv5eAjibaq47fCrWDo8Ms7ijQXlbOwtLeEYX-dqtQDpNNzBfCpDbRmGLJrz4t3xsDBcIutf78aZQMmwTb~KsYdESt~aKNT65Nz4~4BTj-JwWWjWFykJHZXzTfpc~SI0OLOMbEXU3VNlnM0MTA__&Key-Pair-Id=APKAJRICFXQ2S4YUQRSQ",
"commercial_invoice_url": null,
"messages": [],
"order": null,
"metadata": "",
"parcel": "0042019fad6a4a53ace731142a568048",
"billing": {
"payments": []
},
"qr_code_url": null
}
```
### 4. Manifest
DHL eCommerce requires that every label generated is added to a manifest. If you do not create a manifest, your labels will remain on hold. For more information on manifests, see our guide on [Manifests and SCAN forms](/docs/Manifests_and_Pickups/ManifestAndScanForms).
**Request:**
```shell Create manifest request theme={null}
curl --location 'https://api.goshippo.com/manifests/' \
--header 'Content-Type: application/json' \
--header 'Authorization: ShippoToken ' \
--data '{
"address_from": {
"name": "Mr Hippo",
"street1": "965 Mission Street",
"street2": "Suite 480",
"city": "San Francisco",
"state": "CA",
"zip": "94103",
"country": "US",
"phone": "4151234567",
"email": "mrhippo@goshippo.com"
},
"carrier_account": "3579ad96a9534ea2bcc3487e703c98a1",
"shipment_date": "2024-02-09T15:54:17.003Z",
"transactions": ["162b77609c574d499daa9c63d813a845","90909er0erfs343sdsd45sdsd45rtg"],
"async": false
}'
```
**Response:**
```json Create manifest response theme={null}
{
"object_created": "2024-02-09T16:13:22.583Z",
"object_updated": "2024-02-09T16:13:24.634Z",
"object_id": "e830855fbc8e42d7b67b0e00c7592d02",
"object_owner": "adrian.collins@goshippo.com",
"status": "SUCCESS",
"errors": [],
"provider": "dhl_ecommerce",
"shipment_date": "2024-02-09T15:54:17.003Z",
"address_from": "5066d8cc1a0849ea9a08da274e42f54b",
"documents": [
"https://deliver.goshippo.com/e830855fbc8e42d7b67b0e00c7592d02_USLAX1_53219514020916132300.pdf?Expires=1739031204&Signature=X1s6F1H~WGG5qRhOYEPfr3ISuvD0hXXwfKw-npyZHU6~7wzZPw27rIBVUuCtTyd4n~AP8PNu7vq8dUIdvOLhcgJIO7dCr1fnXmLb~C1ufo3bJfD4uN0wcH883Os0pETbjz0Dd~66AsFcgh58FsexSn0U7jIe5F~7vKaWQJkGd4jXX~Lo7fMtIWtfVNlW6KLzr-L2fD5wvB2x8IkPlzbH8t6t4j3f4GXqebtGibcD8JLDuqsYUq3NpnS4Z0~-aamp560SeD0vbuqwQPhMFo1Fo8Hblmw7c4ZiC~0A03D5vb2X2xnl0EhuqcT4hk~FTf-sGKIj~EJnFi5QlLZXN1ZupA__&Key-Pair-Id=APKAJRICFXQ2S4YUQRSQ"
],
"carrier_account": "3579ad96a9534ea2bcc3487e703c98a1",
"transactions": ["162b77609c574d499daa9c63d813a845","90909er0erfs343sdsd45sdsd45rtg"]
}
```
## Hazmat / Dangerous goods
Before attempting to ship hazardous or dangerous goods with DHL eCommerce, we recommend reviewing the [Hazardous Goods and Unacceptable Shipments](https://www.dhl.com/us-en/home/ecommerce/business-help-center/hazardous-goods-and-unacceptable-shipments.html) guide.
To declare hazardous or dangerous goods for DHL eCommerce, use `dangerous_goods_code` in `Extras` when creating a Shipment.
Follow this example to declare dangerous goods in your Shipment.
```shell theme={null}
curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken ' \
--header 'Content-Type: application/json' \
--data-raw '{
"address_from": {
"name": "Mr Hippo",
"street1": "965 Mission Street",
"street2": "Suite 480",
"city": "San Francisco",
"state": "CA",
"zip": "94103",
"country": "US",
"phone": "4151234567",
"email": "mrhippo@goshippo.com"
},
"address_to": {
"name": "Mr Hippo",
"street1": "2967 Filbert Dr",
"street2": "APT 3",
"city": "Walnut Creek",
"state": "CA",
"zip": "94598",
"country": "US",
"phone": "4151234567",
"email": "mrhippo@goshippo.com"
},
"parcels": [{
"weight": "8",
"length": "9",
"width": "3",
"height": "8",
"distance_unit": "in",
"mass_unit": "lb"
}],
"extra": {
"signature_required": "DIRECT",
"dangerous_goods_code": "02"
},
"async": false,
"carrier_accounts":["3579ad96a9534ea2bcc3487e703c98a1"]
}'
```
To learn more about DHL eCommerce dangerous goods codes, refer to [DHL dangerous goods codes](#dhl-dangerous-goods-codes).
## Restrictions
### US Territories
DHL eCommerce supports shipments from US Territories to the US and from the US to the US Territories.
DHL eCommerce does not support shipments between US Territories.
### APO and FPO
APO and FPO are abbreviations used by the US Military Postal Service and Army Post Office.
DHL eCommerce does not support shipments to, from, or between APO and FPO addresses.
## DHL eCommerce Service level tokens
To support our customers who have integrated with Shippo using legacy DHL eCommerce tokens, we have maintained some legacy token naming. Refer to thi stable for more information.
| Token | Shippo Service name | DHL Service name |
| ----------------------------------------------- | -------------------------------- | -------------------------------------------- |
| dhl\_ecommerce\_parcel\_international\_direct | Parcel International Direct | DHL Parcel International Direct |
| dhl\_ecommerce\_parcels\_expedited\_max | Parcels Expedited Max | DHL SmartMail Parcel Expedited Max |
| dhl\_ecommerce\_bpm\_ground | Bounded Printed Matter Ground | DHL SmartMail Bound Printed Matter Ground |
| dhl\_ecommerce\_parcels\_expedited | Parcels Expedited | DHL SmartMail Parcel Expedited |
| dhl\_ecommerce\_parcels\_ground | Parcels Ground | DHL SmartMail Parcel Ground |
| dhl\_ecommerce\_parcel\_international\_standard | Parcel International Standard | DHL Parcel International Standard |
| dhl\_ecommerce\_bpm\_expedited | Bounded Printed Matter Expedited | DHL SmartMail Bound Printed Matter Expedited |
| dhl\_ecommerce\_globalmail\_packet\_priority | GlobalMail Packet Priority | DHL GlobalMail Packet Priority |
| dhl\_ecommerce\_easy\_return\_light | Easy Return Light | DHL SmartMail Parcel Return Light |
| dhl\_ecommerce\_easy\_return\_plus | Easy Return Plus | DHL SmartMail Parcel Return Plus |
| dhl\_ecommerce\_marketing\_parcel\_expedited | Marketing Parcel Expedited [^1] | DHL SmartMail Marketing Parcel Expedited |
| dhl\_ecommerce\_globalmail\_packet\_ipa | GlobalMail Packet IPA [^1] | DHL GlobalMail Packet- IPA |
| dhl\_ecommerce\_marketing\_parcel\_ground | Marketing Parcel Ground [^1] | DHL SmartMail Marketing Parcel Ground |
| dhl\_ecommerce\_globalmail\_packet\_plus | GlobalMail Packet Plus [^1] | DHL Packet Plus International |
[^1]: These service levels are only available to legacy users. New users will not see these service levels.
## DHL eCommerce reference fields
Refer to our [carrier reference fields](/docs/Carriers/CarrierReferenceFields#supported-carriers) guide for details on reference fields used by DHL eCommerce.
To pass billing reference information to DHL eCommerce through the Shippo API, use `reference_2`.
## DHL dangerous goods codes
### Domestic shipments
| Category Code | Description | Max. Weight |
| ------------- | --------------------------------------------------------------- | ----------- |
| 01 | Lithium Metal / Alloy Batteries Contained in Equipment | 11 lbs |
| 02 | Lithium Metal / Alloy Batteries Packed with Equipment | 11 lbs |
| 03 | Lithium Metal / Alloy Batteries Stand-Alone | 5 lbs |
| 04 | Lithium-ion or Lithium Polymer Batteries Contained in Equipment | 11 lbs |
| 05 | Lithium-ion or Lithium Polymer Batteries with Equipment | 11 lbs |
| 06 | Lithium-ion or Lithium Polymer Batteries Stand-Alone | 5 lbs |
| 08 | Limited Quantity / ORM-D | 25 lbs |
| 09 | Small Quantity Provision | 25 lbs |
### International shipments
| Category Code | Description | Max. Weight | Restrictions |
| ------------- | --------------------------------------------------------------- | ----------- | ------------ |
| 01 | Lithium Metal / Alloy Batteries Contained in Equipment | 4.4 lbs | Canada Only |
| 01 | Lithium Metal / Alloy Batteries Contained in Equipment | 11 lbs | Canada Only |
| 02 | Lithium Metal / Alloy Batteries Packed with Equipment | 11 lbs | Canada Only |
| 03 | Lithium Metal / Alloy Batteries Stand Alone | 5 lbs | Canada Only |
| 04 | Lithium-ion or Lithium Polymer Batteries Contained in Equipment | 4.4 lbs | Canada Only |
| 04 | Lithium-ion or Lithium Polymer Batteries Contained in Equipment | 11 lbs | Canada Only |
| 05 | Lithium-ion or Lithium Polymer Batteries Packed with Equipment | 11 lbs | Canada Only |
| 06 | Lithium-ion or Lithium Polymer Batteries Stand Alone | 5 lbs | Canada Only |
| 40 | Limited quantities | 25 lbs | Canada Only |
For more details on category codes, refer to the [DHL eCommerce references](https://api.dhlecs.com/docs/references) guide.