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

Connect your DHL eCommerce accountConnect your DHL eCommerce account response
Copy
Copied
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
}'
Copy
Copied
{
  "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.

note

For 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.

Get rates requestGet rates response
Copy
Copied
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"]
}'
Copy
Copied
{
    "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.

Purchase labelPurchase label response
Copy
Copied
curl --location 'https://api.goshippo.com/transactions/' \
--header 'Authorization: ShippoToken <API_token>' \
--header 'Content-Type: application/json' \
--data '{
  "rate": "b94689b62e8c4fda9e37fd8d61c8ebd4",
  "async": false
}'
Copy
Copied
{
    "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.

Create manifest requestCreate manifest response
Copy
Copied
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
}'
Copy
Copied
{
  "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.

Copy
Copied
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 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

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.

  1. These service levels are only available to legacy users. New users will not see these service levels.

    ↩