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.

noteBefore beginning this guide, you must have your own DHL eCommerce account. Contact your DHL eCommerce account manager to get the required parameters 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. Request:

Connect your DHL eCommerce account

curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken <API_token>' \
--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:

Connect your DHL eCommerce account response

{
  "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.

noteFor international shipments, DHL eCommerces will not return a rate while in test mode. To get a rate, ensure you are using a live token and your carrier is not in test mode.

Request:

Get rates request

curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken <API_token>' \
--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:

Get rates response

{
    "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:

Purchase label

curl --location 'https://api.goshippo.com/transactions/' \
--header 'Authorization: ShippoToken <API_token>' \
--header 'Content-Type: application/json' \
--data '{
  "rate": "b94689b62e8c4fda9e37fd8d61c8ebd4",
  "async": false
}'

Response:

Purchase label response

{
    "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. Request:

Create manifest request

curl --location 'https://api.goshippo.com/manifests/' \
--header 'Content-Type: application/json' \
--header 'Authorization: ShippoToken <API_token>' \
--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:

Create manifest response

{
  "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 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.

curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken <API_token>' \
--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.

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 ¹	DHL SmartMail Marketing Parcel Expedited
dhl_ecommerce_globalmail_packet_ipa	GlobalMail Packet IPA ¹	DHL GlobalMail Packet- IPA
dhl_ecommerce_marketing_parcel_ground	Marketing Parcel Ground ¹	DHL SmartMail Marketing Parcel Ground
dhl_ecommerce_globalmail_packet_plus	GlobalMail Packet Plus ¹	DHL Packet Plus International

DHL eCommerce reference fields

Refer to our carrier reference fields 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 guide.

These service levels are only available to legacy users. New users will not see these service levels. ↩ ↩² ↩³ ↩⁴

Overview

Get started

AI & agents

Guides

Concepts

Get a label from DHL eCommerce

1. Connect your account

2. Get a rate from carrier

3. Purchase label

4. Manifest

Hazmat / Dangerous goods

Restrictions

US Territories

APO and FPO

DHL eCommerce Service level tokens

DHL eCommerce reference fields

DHL dangerous goods codes

Domestic shipments

International shipments

​Get a label from DHL eCommerce

​1. Connect your account

​2. Get a rate from carrier

​3. Purchase label

​4. Manifest

​Hazmat / Dangerous goods

​Restrictions

​US Territories

​APO and FPO

​DHL eCommerce Service level tokens

​DHL eCommerce reference fields

​DHL dangerous goods codes

​Domestic shipments

​International shipments

Footnotes

Get a label from DHL eCommerce

1. Connect your account

2. Get a rate from carrier

3. Purchase label

4. Manifest

Hazmat / Dangerous goods

Restrictions

US Territories

APO and FPO

DHL eCommerce Service level tokens

DHL eCommerce reference fields

DHL dangerous goods codes

Domestic shipments

International shipments