ParcelPilot
Help

DHL Express (MyDHL API)

ParcelPilot’s DHL integration uses the MyDHL API (hostnames like express.api.dhl.com/mydhlapi, api-eu.dhl.com/mydhlapi, api.dhl.com/mydhlapi).

Where do created shipments show up?

DHL has multiple portals/products. Shipments created via the MyDHL API commonly appear in the MyDHL Express portal (the site you found at mydhl.express.dhl). They may not appear in other DHL portals you might also have access to (those can be for different DHL products/accounts).

If you can open an outbound shipment in MyDHL Express and see the waybill/AWB, that confirms the shipment is being created successfully in DHL’s MyDHL system.

Why are some fields “missing” in the portal UI?

  • The MyDHL Express portal screens do not always display every data element that can be sent via API.
  • For domestic shipments (e.g. GB → GB), ParcelPilot does not send export/customs commodity lines (HS code, manufacturer country, etc.) because they are not required.
  • "Piece Description" is not currently set at a per-piece level in ParcelPilot’s payload (we send shipment-level description/reference plus package dimensions/weights). Depending on DHL’s UI/product, this may remain blank.

How to prove what ParcelPilot sent (authoritative)

The most reliable way to confirm which fields were transmitted is to log the DHL request payload.

In Filament:

  • Go to Carrier Credentials → DHL Express.
  • Enable:
    • Debug: log shipment payload (sanitized)
    • (Optional) Debug: log shipment response summary
    • Keep Debug: redact email/phone in logs enabled (recommended)

Logs are written to the carrier log channel:

  • storage/logs/carrier-YYYY-MM-DD.log

Look for entries like:

  • [DHL Express] createShipment payload (sanitized)
  • [DHL Express] createShipment response summary

This is the best way to verify whether HS codes / country of manufacture / line descriptions were included, even if the portal UI doesn’t show them.

What drives customs/commodity fields (international only)

For international shipments, ParcelPilot builds customs commodities from order lines:

  • Item attributes used (when present):
    • attributes.hs_code (digits only; must be at least 6)
    • attributes.origin_country (2-letter ISO)
    • attributes.weight_kg (fallback to item weight/gross weight)

These are mapped into the MyDHL payload export declaration line items.

Common gotchas

  • Environment mismatch: If credentials are set to sandbox, shipments may not appear in production portals.
  • Multiple DHL products: An API key can be enabled for one DHL product/portal but not another.
  • Host mismatch: Some accounts require a different base host (api-eu.dhl.com vs express.api.dhl.com). ParcelPilot attempts common fallbacks, but a Base URL override can be set if DHL support instructs you.

Paperless Trade (WY) + commercial invoice generation (international)

For customs-declarable shipments (typically extra-EU cross-border shipments) that include an export declaration (commodities/line items), DHL may require the Paperless Trade service to be enabled.

What this means:

  • ParcelPilot sends export declaration data (invoice number/date + line items) to MyDHL.
  • For DHL to treat those details as the commercial invoice/customs docs (instead of expecting a separate upload), the shipment must include special service code WY.
  • Some DHL accounts also require explicitly requesting a DHL-generated invoice document in the response.

If DHL IT reports “no invoice uploaded” / “customs docs missing” for an export shipment:

  • Check the carrier log payload for valueAddedServices including WY.
  • Check the payload for content.exportDeclaration having invoice + lineItems.

Invoice output document notes (MyDHL validation behaviour):

  • When requesting an invoice document in outputImageProperties.imageOptions (typeCode invoice), DHL may require fields under content.exportDeclaration.invoice to be present (ParcelPilot sends date + number, and mirrors the shipment reference as an invoice-level customerReferences entry).
  • Some DHL configurations expect a specific invoice template name. If DHL asks for this, set it on the credential as invoice_template_name (common template names seen in DHL guidance include COMMERCIAL_INVOICE_P_10 and COMMERCIAL_INVOICE_L_10).

If WY is missing:

  • DHL will often treat the shipment as needing customs documentation to be uploaded manually, even if export declaration details were provided.

Operational notes:

  • This only applies to shipments that actually require customs/export declaration data (i.e. not GB → GB).
  • Intra-EU shipments typically should not be sent as customs-declarable, and should not require WY.
  • The MyDHL Express portal UI may not clearly show the uploaded/generated invoice, so logs are the most reliable source of truth.

Upload invoice data (PM / upload-invoice-data)

MyDHL also exposes a separate endpoint:

  • PATCH /shipments/{shipmentTrackingNumber}/upload-invoice-data

This is not the same thing as Paperless Trade (WY) or requesting a DHL-rendered invoice document in outputImageProperties.imageOptions.

What it does:

  • It uploads Commercial Invoice (CIN) data to DHL (so DHL can merge it with the shipment).
  • DHL can merge CIN data after shipment creation (or, in some flows, before shipment creation).

Important constraints (per DHL docs):

  • The UploadInvoiceData capability is not enabled by default and must be enabled per customer by DHL Express IT.
  • To use it, the shipment must be created with the PM service code in the Create Shipment request.
  • DHL positions this as an exceptional integration path; they generally recommend sending shipment + invoice data together in the Create Shipment flow.

ParcelPilot status:

  • ParcelPilot currently does not call upload-invoice-data.
  • For normal export flows, ParcelPilot sends invoice/line-item details during Create Shipment and uses WY + (optionally) requests a DHL-generated invoice document.
  • If DHL instructs you to use UploadInvoiceData for a specific account, coordinate enablement of PM/UploadInvoiceData with DHL Express IT first.