Add a DHL Express account

This page walks through the DHL Express-specific steps. The setup steps common to every carrier (sidebar navigation, general settings, save) are described once on Add a carrier account.

Before you start

• DHL Express credentials in hand. From DHL you need: a shipper account number, an API key, and an API secret. Plus the product code matching the service tier your DHL contract covers.
• Decision: live or sandbox. A new carrier account can run against DHL's sandbox before you flip it to live. Smoke-test in sandbox first, then turn on Live Connector.

1. Open the carrier accounts page

In the Carriyo Dashboard, open Settings in the left sidebar.

Under Carrier Management, click Carrier Accounts to open the list of existing accounts.

Click the + add icon in the top-right corner to start a new account.

2. Pick DHL Express

Type DHL into the carrier picker's search field, then click Select on the DHL Express result. DHL has multiple variants in the catalogue (DHL Express, DHL eCommerce, etc.); pick the one matching your contract.

3. Enter the basics

Account name. A label that's meaningful to your ops team. Conventional patterns: dhl-express-uk, dhl-express-eu. Keep it short and unique within the tenant.

Account country. The country the account operates from.

Click Next.

4. Enter your DHL Express credentials

The next two screens collect the credentials DHL issued for your account.

Shipper account number. The nine-digit DHL Express shipper account number provided when your account is created. DHL uses this number to identify you on every API call.

API key and API secret. The API credentials from your DHL Express developer account. Both are required; shipment booking fails if the key or secret doesn't match the account number.

Click Next after each screen.

5. Choose the carrier service

DHL Express lets you set a default service tier per account. For example, Express Worldwide for cross-border, Express Domestic for in-country.

Recommended codes:

• EXPRESS DOMESTIC - Document (N). For domestic shipments.
• EXPRESS WORLDWIDE - Non Document (P). For cross-border.

Click Next, then Go to Account to land on the configured account.

6. Configure the account

The newly created account opens on its detail page.

The general settings (active toggle, country, currency, sandbox/live) are configured the same way for every carrier. See Add a carrier account → General settings for the full walkthrough.

Default label

DHL Express supports its own PDF label format. Pick Use DHL Express PDF Label in the Default Label dropdown to use it as the default for shipments booked with this account.

Callback settings

DHL Express uses manual callback setup. You have to share Carriyo's callback URL and headers with your DHL representative so they can configure DHL's side to push status updates.

Send the URL + headers from this section to your DHL contact. Once they configure DHL's side, status updates flow to Carriyo in real time.

Merchant access

On multi-merchant tenants, restrict the account to specific merchants via the Permissions tab.

Click Save in the top-right corner.

DHL Express-specific concepts

Credentials note

The API Key and API Secret must both match the Shipper Account number. Shipment booking fails if any one is wrong. Contact your DHL representative to obtain these credentials. Staging and production credentials usually differ, so test in sandbox with the staging credentials before flipping Live Connector on.

Payer and duties accounts

If a different DHL account pays the shipping charges (or covers duties and taxes), enter those account numbers in the Payer Account number and Duties & Taxes Account number fields on the account detail page.

Other Service Codes

List any additional DHL value-added services you have registered for (insurance, signature on delivery, Saturday delivery, etc.). Carriyo passes these to DHL when booking shipments.

Customs declarable

For cross-border shipments, enable Customs Declarable so Carriyo includes the full item details in the commercial invoice DHL generates. This supports accurate duty assessment and reduces customs delays.

Incoterms

Pick the applicable Incoterm for cross-border shipments (commonly DDP, Delivery Duty Paid). Configurable per-shipment too.

Default Item Description

Fallback item description used on the label or AWB when no shipment- or item-level description is available. Carriyo's resolution order: parcel description → first item description → this default. Set something meaningful so labels are never blank.

Dangerous goods

If your shipments include hazardous materials, set the Dangerous Goods Service Code, UN Code, and Content ID that DHL provides. These let DHL arrange safe transport and support customs clearance for restricted items. Contact DHL for the exact values that apply to your account.

Booking, exporter, importer, and party details

For international shipments, DHL's commercial invoice can include rich party details (booking requestor, exporter, importer, buyer, seller, shipper, receiver). Each set can include tax registration numbers by issuing country code. Configure these in the corresponding sections of the account detail page so Carriyo populates the invoice consistently.

Document images

You can upload a signature image and a brand logo on the account detail page. DHL prints both on the commercial invoice next to the Signature and Stamp fields.

Label configuration

DHL-specific label options live in the Label section of the account detail page (separate from the generic Default Label dropdown):

• Label Template. The template and size DHL uses to generate the label.
• Waybill Document Template. The format for the waybill document.
• Always download Waybill Document. When enabled, the waybill downloads alongside the label for all shipments, including paperless and domestic ones.
• Enable label-free returns. DHL's paperless return process where customers scan a QR code instead of printing a label. Confirm with DHL that this feature is active on your account before enabling.

Commercial invoice

For cross-border shipments DHL generates a commercial invoice. The Commercial invoice section on the account detail page controls how it's populated:

• Invoice Type. For example, Commercial or Returns.
• Invoice Template. The template DHL uses when generating the invoice.
• Signature Name and Signature Title. Printed on the invoice's signature line.
• Invoice Remarks. Optional remarks shown on the invoice.
• Invoice Declaration. Optional brand-specific declaration text.
• Export Reason. Optional purpose-of-export label (sale, gift, sample, etc.).
• Export Reason Type. Optional, as defined by DHL.

Everything provided here appears on the invoice and supports smooth customs clearance.