Skip to main content
Card class: Hero • Category: Shipping & Courier

​
At a glance

Days until your ShippyPro API auth token expires. When the token expires, every label-print, rate-shop, and tracking call fails immediately, breaking despatch end-to-end until a human re-authenticates. This is the most operational of the operational-health cards: a silent ticking clock that turns into a P1 incident the moment it hits zero.
What it counts(token_expires_at - now) in calendar days, read live from ShippyPro’s /auth/token-info endpoint. Reflects the active OAuth bearer token used by the connector.
API endpointGET /auth/token-info (ShippyPro REST). The card reads token_expires_at, token_id, scopes. The token itself is a long-lived OAuth credential issued via the merchant’s ShippyPro account; expiry is configured at issue time (typical 365 days, some workspaces 180 or 90).
Delivery success criterionNot applicable, this is connector health, not delivery.
On-time thresholdNot applicable.
Returns / RTONot applicable.
Service level scopeSingle token covers all carriers and services connected through the workspace.
What “expired” actually breaksEvery operational call: rate-shop quotes, label generation, tracking polls, manifest collection, claims filing. Despatch stops; existing in-flight shipments continue tracking via webhook (carrier-direct), but new orders cannot be processed.
Time windowRT (real-time, refreshed on connector poll cycle, typically every 5 to 15 minutes)
Alert trigger<14 days. Tripped at 14 days remaining. The 14-day cushion is enough for a non-urgent re-auth window through normal change-management; below 7 days is a P2 escalation.
Rolesowner, operations

​
Calculation

Calculated automatically from your ShippyPro 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 Italian DTC fashion brand. Reading taken at 09:00 CET on 12 Mar 26.
WorkspaceToken issuedToken expiresDays remainingAlert state
brand-it (primary)14 Mar 2514 Mar 262CRITICAL, <7 days
brand-fr (secondary)22 Sep 2522 Sep 26193Healthy
The card reads 2 days for the primary workspace; the alert at <14 days has been firing for 12 days already. Five things to notice:
  1. The clock has been counting down for 363 days; nobody noticed for 351 of them. This is the failure mode of token-expiry: silent until it isn’t. The 14-day alert is meant to guarantee humans notice with two weeks of cushion. If the alert was acknowledged but the rotation work was deprioritised, escalate now.
  2. Two days is a P1 weekend risk. If the token expires at 14 Mar 26 03:00 CET (the original issue timestamp), Saturday morning despatch breaks. Operations on Monday will find unprocessable orders backlog from Sunday plus Saturday overflow. The fix window before P1 is the next business day; rotate today.
  3. The fr workspace is healthy and is the rollback path. If the it rotation goes wrong, the fr token can technically print labels for it shipments via a workspace switch, with manual rate-card and template overrides. Document the rollback path before rotating.
  4. Re-auth requires a human in ShippyPro’s UI. The OAuth flow needs an admin user to log into ShippyPro Settings → API & Integrations → Generate New Token, copy the new bearer, paste into the Vortex IQ connector settings. Coordinate the rotation with despatch downtime (typically <5 minutes if pre-staged).
  5. After rotation, the card resets to 365 days (or whatever the issue-time window is). Re-read the card 24 hours after rotation to confirm the new expiry has propagated; if the card still shows <14 days the new token did not save correctly. Record the rotation in the change-history block of the workspace.

​
Sibling cards merchants should reference together

Token-expiry is binary at the day level (alert fires or not), but it is a leading indicator for a chain of operational cards. Pair with these to anticipate impact:
CardWhy pair it with Days to Token ExpiryWhat the combination tells you
API Error RateLagging confirmation. Token expiry produces 401 Unauthorized errors.Error rate rising while expiry days drop = token already partially failing. Should never get this far if the alert was respected.
Label Generation SuccessThe downstream effect of an expired token.Drops to 0 percent the moment the token expires. Watch this card during and immediately after rotation.
ShipmentsTotal volume processed; goes to zero on token expiry.Confirms the operational impact of expiry; combined with Label Generation Success tells you whether despatch is broken.
Cross-connector: any other connector’s token-expiry cardWorkspace-wide rotation hygiene.Multiple connectors with simultaneous low expiry days = the merchant’s API-token rotation cycle is overdue across the stack. Schedule a quarterly token-rotation calendar.
Cross-connector: alerting / on-call rota (PagerDuty etc.)Ensures the alert from this card actually wakes someone.If the alert fires but no rota acknowledges, the silent-expiry failure mode returns.

​
Reconciling against the vendor’s own dashboard

Where to look in ShippyPro’s own dashboard: ShippyPro Settings → API & Integrations. The page lists the active token, issue date, expiry date, and a “Rotate” button. The card and the portal read the same source; numbers should match exactly. If they differ by more than a few minutes, the connector poll cycle is stale and a manual reconnect refreshes the read. Why our number may legitimately differ from ShippyPro’s portal:
ReasonDirectionWhy
Connector poll lagOurs up to 15 minutes behindThe card refreshes on the connector’s standard poll cadence; the portal reads live. Variance is small and never exceeds 1 day.
Workspace selectionEither, if multi-workspaceMulti-workspace merchants must connect each token separately; the card reads only the connected workspace. The portal toggles per workspace.
Token regeneration without disconnectCard stale until reconnectIf a merchant rotates the token in ShippyPro’s portal without re-saving the new token in Vortex IQ, the card reads the old (now expired) token’s expiry. This is the most common false-alarm; reconnect resolves.
Cross-connector reconciliation:
CardExpected relationshipWhat causes legitimate divergence
Other shipping connectors’ auth-token cardsIndependent tokens; correlation only via rotation policy.Merchants who rotate all tokens on a quarterly calendar will see them age in lockstep.
Webhook-health monitorsToken expiry breaks API but not webhooks (carriers post directly to ShippyPro).Until the next outbound API call needed by the connector.

​
Known limitations / merchant FAQs

Why does ShippyPro use expiring tokens at all? Other connectors use long-lived API keys. Security policy. ShippyPro’s OAuth model rotates the bearer to limit exposure if a token leaks. Most workspaces are issued 365-day tokens; enterprise accounts can request 180 or 90-day windows. The trade-off is operational: shorter windows mean more rotation work but smaller credential-exposure blast radius. The token expired and despatch is broken. What is the recovery time? Rotation itself takes 5 to 10 minutes if you have ShippyPro admin access ready. After re-saving in Vortex IQ, the connector resumes API calls within one poll cycle (5 to 15 minutes). The backlog of unprocessed orders since expiry then needs to be re-queued; tools like Vortex IQ’s connector-resync command handle this. Total restoration typically 30 minutes; longer if you need to wait for an admin user. Can I rotate proactively before expiry? Yes, recommended. ShippyPro lets you generate a new token before the old one expires; both are valid simultaneously for a few hours of grace. Rotate at the 30-day mark on a calendared cadence, not in firefighting mode. The card will reset to 365 days post-rotation. Why does the alert fire at 14 days specifically? The 14-day threshold is conventional across cloud-platform secret rotation. Two business weeks is enough cushion for change-management approval, off-hours rotation scheduling, and rollback if the new token has issues. Below 7 days the alert escalates to P2; below 2 days it should be P1. Multi-workspace merchants, does each token need separate rotation? Yes, each ShippyPro workspace has its own token; each must be rotated independently. The card surfaces them as separate workspace entries (if the connector is configured per workspace). Build a rotation calendar that staggers them so you never have two workspaces expiring in the same week. What happens to in-flight shipments when the token expires? Already-printed labels continue tracking via carrier webhooks (the carrier posts to ShippyPro directly, not through your connector). The visible breakage is on new shipments: cannot rate-shop, cannot print labels, cannot file claims. Existing-claim status updates may also lag. Why is this card hero-tier and not standard? Because token expiry is the single failure mode that takes despatch from “running” to “broken” in zero time. Other operational-health cards (API error rate, label generation success) trend gradually; expiry is binary at zero. Can I automate token rotation? Partially. ShippyPro’s API supports programmatic token issuance once an admin has authorised the OAuth client. A workspace can run a quarterly rotation script that issues a new token, posts it to Vortex IQ via API, and revokes the old one. This reduces the human-in-loop window but the OAuth handshake still requires periodic re-authorisation (typically annually). My token says “never expires” but the card shows a number. Why? Some legacy ShippyPro accounts have non-expiring API keys. The connector falls back to a synthetic 365-day expiry from the issue date for display; this is a placeholder and will not actually expire. Set the alert to “ignore” for these accounts to suppress false alerts.

​
Tracked live in Vortex IQ Nerve Centre

Days to Token Expiry is one of hundreds of KPI pulses Vortex IQ tracks across ShippyPro and 70+ other ecommerce connectors. Nerve Centre runs the detection layer; Vortex Mind investigates the cause when something moves; Ask Viq lets you interrogate any number in plain English. Start for free or book a demo to see this metric running on your own data.