At a glance
Silent-failure tripwire for the PostNord connection. PostNord’s API access tokens (issued via the Business Portal API Access page) typically have a 90 to 365-day TTL depending on the contract type. When they expire, label-printing, tracking-events ingestion, and claims-API access all stop silently. This card lights up 14 days before the token TTL elapses so the merchant can rotate it before parcel-flow stops.
| What it tracks | Days remaining until the configured PostNord API token’s expires_at claim. Pulled from the token introspection endpoint. |
| Token type covered | PostNord Shipping API tokens (used for label generation), Tracking API tokens (used for event ingestion), and Claims API tokens (used for claims management). The card surfaces the earliest expiring of all configured tokens, fixing the soonest-expiring is the priority. |
| Why a hero card on a shipping connector | Token expiry is silent. Without this card the merchant only discovers the outage when label generation starts failing at the warehouse, which means parcels miss their dispatch window and OTD takes a day-or-two hit before anyone notices. Merchants typically lose 50 to 200 parcels per day of outage at the warehouse-floor level. |
| Merchant impact link | Each day past expiry: (1) label-print fails, parcels sit unshipped at the warehouse; (2) tracking-events stop ingesting, Exception Rate goes silent (false-low reading); (3) claims API rejects new filings; (4) Late Shipments spikes 1 to 2 days after expiry as the unshipped backlog cascades. |
| Renewal flow | Click Rotate token on the card; Vortex IQ deep-links to PostNord Business Portal → API Access. Generate a new token, paste into Vortex IQ. Most merchants generate tokens with the maximum TTL (typically 365 days for Tracking, 90 days for Shipping) to minimise rotation frequency. |
| Multi-account aggregation | If the merchant runs multiple PostNord marketer accounts (one per Nordic country), the card shows the minimum days remaining across all configured tokens. Drill-down shows per-account TTLs. |
| Refresh cadence | Hourly. The 14-day alert window doesn’t need second-by-second resolution. |
| Time window | RT (current TTL). |
| Alert trigger | <14 days. Three states: healthy (>14 days), warn (<14 days), critical (expired). |
| Roles | owner, operations |
Calculation
Calculated automatically from your PostNord data. See the At a glance summary above for what the metric tracks and the worked example below for a typical reading.Worked example
The Stockholm outdoor-apparel brand. Reading taken at 08:00 CET on 26 Mar 26. The card displays:Earliest token expires in 9 days (Shipping API token, expires 04 Apr 26 at 14:00 UTC) Status: WARN Action: [Rotate token now]
| Token | Account | Expires | Days remaining | Used for |
|---|---|---|---|---|
| Shipping API | PostNord SE | 04 Apr 26 | 9 | Label generation; warehouse-blocking if expires |
| Shipping API | PostNord DK | 11 Apr 26 | 16 | Same, DK lane |
| Tracking API | PostNord SE | 14 Sep 26 | 172 | Event ingestion |
| Tracking API | PostNord DK | 14 Sep 26 | 172 | Same, DK |
| Claims API | PostNord SE | 02 Jul 26 | 98 | Claims filings |
- 9 days until label-print fails on the SE lane. SE is 65 percent of volume; a 9-day outage would block roughly 7,500 parcels at the warehouse. Rotate now.
- The DK Shipping token is also approaching warn threshold (16 days). Plan to rotate both Shipping tokens in the same maintenance window to avoid having to repeat the procedure twice in 7 days.
- The Tracking and Claims tokens are healthy. No action needed; they have months of TTL.
- Cost of doing nothing for 9 days. On 04 Apr the Shipping API stops; warehouse can’t print PostNord labels. Pre-existing labels still scan (no immediate dispatch failure), but new orders printing pile up. Within 24 hours of expiry, Late Shipments starts climbing as the backlog cascades; within 3 days OTD drops 5 to 10 percentage points.
- The rotation is 90 seconds of work. Click Rotate token on the card → Vortex IQ deep-links to PostNord Business Portal → generate new token with 90-day TTL → copy → paste back into Vortex IQ → save. The card flips to healthy (TTL ~90 days) within 60 minutes.
- Post-rotation verification. Print a test label via Vortex IQ → Connectors → PostNord → Test Label. If it returns a valid PDF, label-print is working. Pair with the API Error Rate card; the rate should drop to baseline within minutes of rotation.
Sibling cards merchants should reference together
| Card | Why pair it with Days to Token Expiry | What the combination tells you |
|---|---|---|
| API Error Rate | Real-time API health. | Token expiry shows error rate climbing to 100 percent on label-print endpoint; this card is the leading indicator. |
| Label Generation Success | The downstream label-print health. | Drops to zero on token expiry; this card prevents the drop. |
| Late Shipments | Cascading downstream impact. | Token expiry → label-print fails → warehouse backlog → late shipments rise 1 to 3 days later. |
| OTD Rate | Quality dial; the lagging indicator of an unaddressed token expiry. | Token expired and not rotated within 7 days drops OTD by 5 to 10 percentage points. |
| Exception Rate | Goes false-low when Tracking API token expires (events stop ingesting). | Sudden flat-line on exception rate may be tracking-token expired, not actual quality improvement. |
| Open Claims | Claims-API access. | Claims API token expiry blocks new filings; queue stalls until rotation. |
Cross-connector: bring.bri_token_expiry_days, royal_mail.roy_token_expiry_days | Same pattern, different carriers. | Coordinated rotation cadence avoids back-to-back outages. |
Cross-connector: shopify.shopify_session_health | Adjacent connector-token-health peer. | Multi-connector rotation campaigns are easier when all token-health is on one dashboard. |
Reconciling against the vendor’s own dashboard
Where to look in PostNord: PostNord Business Portal → Account → API Access. This page lists every PostNord API token attached to the merchant’s account, with name, scope, and TTL. The token Vortex IQ uses appears with the name set at connector setup (defaultVortex IQ Connector - {scope} per token type).
The portal shows TTL in absolute terms (e.g. Expires 04 Apr 2026); this card converts to a remaining-days countdown.
Why our number may legitimately differ from the portal:
| Reason | Direction | Why |
|---|---|---|
| Refresh cadence | Ours up to 1 hour stale | Card polls hourly; portal is real-time. |
| Time zone | Same | Day-count is unaffected; absolute date may differ by 1 day at midnight boundaries. |
| Manually-revoked tokens | Ours overstated immediately after revocation | If an admin manually revokes a token, the card may show 30 to 60 minutes of stale TTL until the next poll fails. |
| Multi-token aggregation | Ours shows minimum | Card surfaces the earliest-expiring token; portal shows each independently. To see all, drill down on the card. |
| Token rotation race | Ours briefly shows old TTL | Just after a successful rotation, the card may briefly show the old TTL until the next poll picks up the new one. |
| Card | Expected relationship | Causes of legitimate divergence |
|---|---|---|
bring.bri_token_expiry_days | Adjacent Nordic carrier; same TTL pattern. | Independent token TTLs; rotation cadences should be synchronised to avoid cross-cancelling outages. |
royal_mail.roy_token_expiry_days | Different region, same pattern. | Different vendor policies (Royal Mail OAuth refresh tokens auto-renew; PostNord’s PATs do not). |
jira.jira_alert_token_expiry_imminent | Same TTL pattern, different vendor domain. | Many merchants rotate all connector tokens on a quarterly campaign; this card is one input. |
| Vortex IQ Connector Health Index | This card is one input. | Multiple connector tokens nearing expiry simultaneously degrades the index; coordinated rotation clears it. |
Known limitations / merchant FAQs
Why does the token expire? Can I make it permanent? PostNord enforces TTLs on API tokens for security; max TTL varies by scope (Tracking can go to 365 days, Shipping typically capped at 90 days, Claims at 180 days). The 90-day Shipping token is the most frequent rotation; this is unavoidable on PostNord’s current API model. Some larger contracts negotiate longer TTLs with PostNord IT; ask your account manager. My token expires in 9 days but it’s the weekend. Can I rotate Monday? Technically yes (9 > 0), but the safer pattern is to rotate the moment the alert fires. PostNord occasionally pushes early-expiry events for tokens that haven’t been used in 30+ days; the displayed TTL is not always the actual TTL. Rotate when prompted. The card says expired but Vortex IQ is still printing labels. How? Most likely cause is a stale poll, the card hasn’t refreshed since you rotated. Wait 60 minutes for the next poll, or click Refresh now on the card. Less likely: PostNord sometimes honours a brief grace period (typically 24 hours) on expired tokens for in-flight requests; the card cannot see that grace. My warehouse is printing labels but Vortex IQ shows the token expired. Why? Most warehouses use PostNord’s own desktop label-print software (Click&Drop or equivalent), which has its own auth credentials independent of Vortex IQ’s connector token. The Vortex IQ token is for Vortex IQ-side label generation and tracking-event ingestion, not for the warehouse’s own systems. So the warehouse keeps printing while Vortex IQ goes dark on tracking visibility, leading to the exception rate going false-low pattern. Rotate the Vortex IQ token to restore visibility. Can Vortex IQ rotate the token automatically? No. PostNord’s token-creation requires the user’s browser-session forPOST /tokens; there’s no headless API for programmatic creation. The merchant must click through PostNord’s portal to create the new token. Vortex IQ deep-links to the right screen and pre-fills the recommended name. Total time: ~90 seconds.
I rotated the token but label-printing is still failing. What now?
Five-minute checklist. (1) Click Test Connection on the connector page; the API call returns the specific error code. (2) Verify the new token has the correct scope (Shipping API, not just Tracking). (3) Verify the new token’s account ID matches the marketer-account configured in Vortex IQ. (4) Check API Error Rate for the specific error type. (5) If still failing, the new token may be missing a required scope; regenerate with the Default scope set, do not narrow scopes manually.
Multi-account, do I need to rotate tokens for each Nordic country separately?
Yes, each marketer account has its own token. The card surfaces the earliest-expiring across all configured tokens; rotating that one is the priority. Many merchants run a quarterly rotation campaign rotating all 4 country accounts simultaneously to minimise rotation friction.
The alert window is 14 days. Can I make it 30 or 7?
Yes, in Settings → Alerts → PostNord Token Expiry. The default 14-day threshold is calibrated for typical merchant operations cadence; teams handling rotations on weekly tickets often prefer 30 days. The trade-off: longer windows mean amber-state for longer, with potential alert fatigue.
Does this card track every PostNord token I have, or just the one Vortex IQ uses?
Just the ones Vortex IQ uses. If your team has separate PostNord tokens for warehouse software, ERP integration, etc, those are not visible here. The PostNord portal is the source of truth for the full list.
The token was revoked by my PostNord account admin during a security audit. What happens?
The card flips to expired (critical) within an hour. Label-printing fails. Coordinate with the admin to issue a replacement, then click Rotate token on the card and paste the new value. Pre-existing parcels with already-printed labels still scan; only new labels are blocked. Plan for a 1 to 4 hour outage during admin-coordinated rotation if it falls during peak warehouse hours.
Why is this called “Days to Token Expiry” rather than “Token Health”?
The metric is the days-remaining countdown. Other token-health signals (last-used timestamp, scope correctness) are separate cards (when present). This card focuses on the highest-leverage signal, the rotation deadline.