Skip to content

Shipment Tracking

Overview

The Hermes Connector provides automatic shipment tracking. When tracking is enabled, open shipments are periodically queried from the Hermes API and status changes are recorded as events.

Enable Tracking

  1. Open the Hermes Setup
  2. Set Tracking Enabled to Yes
  3. Set the Poll Interval (in minutes)
Setting Recommendation Description
Tracking Enabled Yes Enable automatic status polling
Poll Interval 60–120 min. More frequent = more current data, but higher API load

Performance

An interval of 60 minutes is sufficient for most use cases. The Hermes API has rate limits — overly frequent queries may be blocked.

Tracking Statuses

Status Overview

Status Symbol Meaning
Picked Up 📦 Shipment has been picked up
In Transit 🚚 Shipment is in transit within the Hermes network
Out for Delivery 🏠 Shipment is on the last mile (delivery)
Delivered ✅ Successfully delivered
Returned ↩️ Shipment was returned to sender
Exception ⚠️ Delivery error (recipient not found, address error)

Status Transitions

stateDiagram-v2
    [*] --> PickedUp: Pickup
    PickedUp --> InTransit: Depot Arrival
    InTransit --> OutForDelivery: Last Mile
    OutForDelivery --> Delivered: Delivery Successful
    OutForDelivery --> Exception: Delivery Failed
    Exception --> InTransit: Retry
    Exception --> Returned: Return to Sender
    InTransit --> Returned: Undeliverable

Tracking Events

Each status change is stored as a Tracking Event. The event history shows the complete journey of a shipment:

Field Description
Timestamp Date and time of the event
Status New shipment status
Location Location of the event (depot, delivery vehicle, PaketShop)
Description Detailed description of the event

View Events

  1. Open the merchantCENTRAL Shipment List
  2. Select a shipment with a tracking number
  3. Click Tracking History (or open the shipment details)
  4. The event list shows all status changes chronologically

Proof of Delivery

After successful delivery, a digital Proof of Delivery (POD) can be retrieved:

  • Digital signature of the recipient
  • Delivery time (exact date and time)
  • Delivery location (doorstep, neighbor, PaketShop)

Availability

The Proof of Delivery is not immediately available after delivery. It may take a few hours until the data is available in the system.

Automatic Processing

Job Queue Integration

Tracking is managed via the Hub's Job Queue mechanism:

  1. The Hub automatically creates a Job Queue Entry for tracking
  2. The job runs at the configured interval
  3. Only open shipments (not delivered, not returned) are queried
  4. Delivered shipments are automatically removed from the tracking loop

Hub Events

The Hermes Connector responds to the following Hub events:

Event Description
OnGetTrackingStatus Query tracking status for a single shipment
OnGetProofOfDelivery Retrieve Proof of Delivery (POD) for a shipment

Error Cases

Situation Behavior
API not reachable Query is retried at the next interval
Invalid tracking number Shipment is removed from tracking, error logged
Rate limit reached Query is automatically paused and resumed at the next interval

Limitations

Limitation Description
Hermes shipments only Tracking only works for shipments created via this connector
No real-time tracking Status is polled periodically, no webhook/push
Domestic shipments Tracking only available for German shipments