# DHL eCommerce 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 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 { "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 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 { "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 curl --location 'https://api.goshippo.com/transactions/' \ --header 'Authorization: ShippoToken ' \ --header 'Content-Type: application/json' \ --data '{ "rate": "b94689b62e8c4fda9e37fd8d61c8ebd4", "async": false }' ``` **Response:** ```json { "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 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 { "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 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.