DHL

Track DHL shipments by tracking number

Overview

DHL is a global logistics company providing shipping and tracking services. This tool queries the DHL Unified Tracking API to retrieve tracking details for shipments by their tracking number. It returns shipment status, origin/destination, tracking events, and delivery details. Optionally accepts a recipient postal code for more detailed information.

Category: Utility
Tool Name: dhl
Version: 1

Appearance: Icon: lucide-Truck | Color: #FFCC00

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires DHL API credentials. See the Credentials Guide for setup instructions.

Operations

Operation	Value	Description
Get Tracking Details	get	The operation to perform.

Parameters

Parameter	Type	Required	Default	Description
Tracking Number	string	Yes	—	The DHL tracking number of the shipment to look up. Supports expressions like {{ $json.trackingNumber }}.
Options	collection	No	{}	Additional options for the tracking request.
— Recipient’s Postal Code	string	No	—	DHL will return more detailed information on the shipment when you provide the recipient’s postal code. It acts as a verification step. Supports expressions.
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

Each shipment the API returns becomes its own output item: the shipment object is merged into the incoming item JSON at the top level, so the upstream fields stay addressable alongside the tracking data. Binary data is forwarded. One input item can therefore produce several output items when a tracking number resolves to more than one shipment.

Merged shipment data covers the shipment’s status, origin and destination, and its tracking events, along with the delivery details DHL exposes for that shipment. Supplying the recipient’s postal code makes DHL return a more detailed record.

When the tracking number matches nothing, one item is emitted carrying the original JSON plus:

{
  "_trackingNumber": "1234567890",
  "_shipments": []
}

Check _shipments before treating a result as a real shipment — an empty array is the “not found” signal, not an error.

Usage Examples

• Get tracking details for a DHL shipment
• Check the delivery status of a DHL package
• Look up DHL tracking events for a parcel

Example Configuration

Track a single package by a tracking number carried on the item:

{
  "type": "dhl",
  "parameters": {
    "operation": "get",
    "trackingNumber": "{{ $json.trackingNumber }}"
  }
}

Ask for the detailed record by verifying with the recipient’s postal code:

{
  "type": "dhl",
  "parameters": {
    "operation": "get",
    "trackingNumber": "{{ $json.trackingNumber }}",
    "options": {
      "recipientPostalCode": "{{ $json.shipTo.postalCode }}"
    }
  }
}

Track a batch of numbers with a higher concurrency:

{
  "type": "dhl",
  "parameters": {
    "operation": "get",
    "trackingNumber": "{{ $json.awb }}",
    "maxConcurrency": 20
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Track DHL shipments by tracking number using the DHL Unified Tracking API.

Important Notes

• Parameter structure. options is a collection — its fields nest under the options key. Do not place recipientPostalCode at the top level of the parameters object.
• Required fields. trackingNumber is required for every tracking request.
• One operation. get is the only operation available; the tool always reads tracking data and never writes to DHL.
• Fan-out. Because each shipment leaves as its own item, downstream nodes see one item per shipment rather than one per input item.