At a glance
Days remaining until the DHL Geschaftskundenportal API credential behind your Deutsche Post connection stops authenticating. When the token expires every booking, label-generation, tracking-event ingestion and Reklamationsstelle claim call from Vortex IQ to DHL fails with HTTP 401 at once. Nothing is wrong with delivery itself; the connector simply goes dark. The hero placement exists because an expired credential takes the whole despatch operation offline with no gradual warning, only a 14-day countdown.
Calculation
Calculated automatically from your Deutsche Post connection metadata. The connector records the expiry returned by the DHL token endpoint each time it authenticates, subtracts the current time and floors to whole days. Three credential horizons can drive this number, and the card always shows the nearest actionable one:- Access token. Short lived (roughly one hour for the DHL flow). The connector refreshes these automatically, so they self-heal and are never the headline.
- Refresh token. The medium horizon. For the standard Vertragskunden OAuth setup the refresh token carries a multi-month life (commonly around 12 months) and must be renewed by re-authorising the connection through the portal.
- API key / app registration. Older Online-Frankierung integrations may use a longer-lived API key on a fixed rotation. These do not expire on the OAuth clock but can be revoked or flagged for periodic review; the connector treats a known review date as an expiry horizon.
floor(min(refresh_expiry, key_review_date) - now) in days. The auto-refreshing access token is deliberately excluded, because reporting it would peg the card near 0 and make it useless.
Worked example
A Dusseldorf-based DTC homeware merchant, around 6,400 parcels per week, ships almost entirely on DHL Paket (Inland) with a DHL Paket International leg for AT and CH orders. They connected Deutsche Post to Vortex IQ via the standard Geschaftskundenportal OAuth flow. The refresh token was issued on 12 Mar 25 with a 12-month rotation, due to expire on 12 Mar 26. Reading taken at 09:00 CET on 27 Feb 26:
The card reads 13 days. The alert at
<14 days is tripped: the dashboard turns amber and the integration owner is emailed. Four things to notice:
- The access token does not drive the number. It expires hourly and refreshes silently. If the card reported that it would always read 0. The card correctly reports the 13-day refresh-token horizon.
- The rotation playbook is short, run it now. Log into the DHL Geschaftskundenportal, open Einstellungen, Entwickler, API-Zugang, generate new access credentials, copy the
client_idandclient_secret, paste them into Vortex IQ under Integrations, Deutsche Post, Update Credentials, then test the connection. Five to eight minutes for a familiar user. The portal lets old and new credentials overlap briefly, so there is no hard cutover. - When this hits 0, these cards go stale, not red. Label Generation Success, Retouren-Etikett Generation Failure Rate, On-Time Delivery Rate and every tracking-driven card stop receiving fresh data. They do not show a delivery problem; they show no new data. Bookings fail loudly with 401; tracking fails silently until someone notices missing scans.
- Peak timing matters. This token expires 12 Mar 26, clear of Q4. A merchant whose credential would lapse in late November should rotate in October rather than risk a re-consent during Black Friday week, when nobody has time to chase a portal login.
Sibling cards merchants should reference together
Token expiry is an availability metric, not a performance one. Pair it with the other operational-health and label cards to understand blast radius:Reconciling against the source
Where to look in DHL’s own tooling: The authoritative record of credential validity is the DHL Geschaftskundenportal, under Einstellungen, Entwickler, API-Zugang, which lists active and expired credentials withErstellt am (created), Gultig bis (valid until) and Letzte Nutzung (last used). The DHL Developer Portal holds the application registration and consumer key for the underlying API app. The card reading should match the active credential’s Gultig bis to within a day; if it differs by more than a day, force a refresh under Integrations, Deutsche Post, Refresh Credentials.
There is no aggregator layer here: Deutsche Post / DHL is a single national carrier, not an EasyPost or Shippo style multi-carrier API, so the only two sources of truth are the two DHL portals above. If you run DHL behind an aggregator, reconcile against the aggregator’s connection-health page as well.
Why our number may legitimately differ from DHL’s portal:
Known limitations / merchant FAQs
My token rotates every 12 months. Why does the alert fire 14 days early? The 14-day window is the safe buffer for a human-led rotation. Leaving it to the day before gives under 24 hours to log in, generate, paste, test and verify, which is too tight for a Friday afternoon. Fourteen days lets you schedule the work and recover from a failed test. If your operations cadence supports it, the threshold can be tightened to 7 days per store; below 7 is operationally risky. The card says “expired” but my Deutsche Post integration still works. Why? Three possibilities. (1) Sync lag: the card is reading a cached expiry, so force a refresh. (2) Overlapping credentials: the portal often lets an old and new pair co-exist for 24 to 48 hours after rotation. (3) Wrong credential record: if an integration was disconnected and reconnected, a dead record may still be read, so reconnect to be safe. What exactly stops working when this hits 0? Everything that calls DHL: new shipping labels, Retouren-Etikett (return label) generation, rate quotes, tracking-event ingestion and Reklamationsstelle claim sync. Parcels already in the DHL network keep moving physically; you simply stop getting scans and cannot create new labels. The visible symptom is several cards freezing at their last-known values at once. Can I rotate the credential before the alert fires? Yes, and that is the preferred pattern. Set a recurring reminder (for example every quarter, aligned to a quiet trading week) and rotate proactively. The Geschaftskundenportal generates new credentials without invalidating the old ones immediately, so there is no outage during rotation. My API credentials were generated by a colleague who has left. Should I rotate? Yes, immediately. Generation is bound to a Geschaftskundenportal user; if that account is deactivated the credentials can stop working without notice. Best practice is to generate against a shared operations service account rather than a personal login, and rotate whenever the binding user changes role. Does the alert fire on access-token or refresh-token expiry? Refresh-token. Access tokens expire roughly hourly and refresh automatically, so the card does not surface them. The refresh token carries the multi-month horizon and requires re-authorisation when it lapses. For most Deutsche Post merchants this is a once-a-year, structural event per integration. The portal shows my credential as “Aktiv” but the card says expired. Who is right? The card. It reads theexpiry_at stamped on the credential; if DHL has not yet run its housekeeping at the expiry moment the portal may still show “Aktiv”, but every API call after that point fails with 401. Trust the card and rotate.
Can I get a webhook instead of an in-dashboard alert?
Yes. The integration-health alert framework delivers to Slack, Teams or email. Configure it once at integration level; the same trigger that lights this card fires the webhook. Many German operations teams route these to a dedicated integration-health channel.