Skip to content
/
DHL eCommerce
Last updated

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.

Request:

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:

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

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:

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

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

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:

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:

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

TokenShippo Service nameDHL Service name
dhl_ecommerce_parcel_international_directParcel International DirectDHL Parcel International Direct
dhl_ecommerce_parcels_expedited_maxParcels Expedited MaxDHL SmartMail Parcel Expedited Max
dhl_ecommerce_bpm_groundBounded Printed Matter GroundDHL SmartMail Bound Printed Matter Ground
dhl_ecommerce_parcels_expeditedParcels ExpeditedDHL SmartMail Parcel Expedited
dhl_ecommerce_parcels_groundParcels GroundDHL SmartMail Parcel Ground
dhl_ecommerce_parcel_international_standardParcel International StandardDHL Parcel International Standard
dhl_ecommerce_bpm_expeditedBounded Printed Matter ExpeditedDHL SmartMail Bound Printed Matter Expedited
dhl_ecommerce_globalmail_packet_priorityGlobalMail Packet PriorityDHL GlobalMail Packet Priority
dhl_ecommerce_easy_return_lightEasy Return LightDHL SmartMail Parcel Return Light
dhl_ecommerce_easy_return_plusEasy Return PlusDHL SmartMail Parcel Return Plus
dhl_ecommerce_marketing_parcel_expeditedMarketing Parcel Expedited [^1]DHL SmartMail Marketing Parcel Expedited
dhl_ecommerce_globalmail_packet_ipaGlobalMail Packet IPA [^1]DHL GlobalMail Packet- IPA
dhl_ecommerce_marketing_parcel_groundMarketing Parcel Ground [^1]DHL SmartMail Marketing Parcel Ground
dhl_ecommerce_globalmail_packet_plusGlobalMail 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 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 CodeDescriptionMax. Weight
01Lithium Metal / Alloy Batteries Contained in Equipment11 lbs
02Lithium Metal / Alloy Batteries Packed with Equipment11 lbs
03Lithium Metal / Alloy Batteries Stand-Alone5 lbs
04Lithium-ion or Lithium Polymer Batteries Contained in Equipment11 lbs
05Lithium-ion or Lithium Polymer Batteries with Equipment11 lbs
06Lithium-ion or Lithium Polymer Batteries Stand-Alone5 lbs
08Limited Quantity / ORM-D25 lbs
09Small Quantity Provision25 lbs

International shipments

Category CodeDescriptionMax. WeightRestrictions
01Lithium Metal / Alloy Batteries Contained in Equipment4.4 lbsCanada Only
01Lithium Metal / Alloy Batteries Contained in Equipment11 lbsCanada Only
02Lithium Metal / Alloy Batteries Packed with Equipment11 lbsCanada Only
03Lithium Metal / Alloy Batteries Stand Alone5 lbsCanada Only
04Lithium-ion or Lithium Polymer Batteries Contained in Equipment4.4 lbsCanada Only
04Lithium-ion or Lithium Polymer Batteries Contained in Equipment11 lbsCanada Only
05Lithium-ion or Lithium Polymer Batteries Packed with Equipment11 lbsCanada Only
06Lithium-ion or Lithium Polymer Batteries Stand Alone5 lbsCanada Only
40Limited quantities25 lbsCanada Only

For more details on category codes, refer to the DHL eCommerce references guide.

Previous page
Next page