At a glance
Days remaining until the Shippo API token used by Vortex IQ to read shipment, transaction, and tracking data expires. The “is the connector about to silently break?” countdown, surfaced before downstream cards start showing stale data.
| What it counts | expires_at - now() for the active Shippo API token bound to this workspace. Computed in days (rounded down). Live tokens that do not have a published expiry return null, which renders as ”-” on the card. |
| API endpoint | Shippo GET /api/keys/{key_id} (admin endpoint). Read once per polling cycle; token remaining-life is cached in Vortex IQ for 1 hour. |
| Token type | Two flavours. Live API token (production, no expiry by default; the value here is null and the card shows ”-” or 365+). OAuth-issued token (used for partner integrations; 30-day refresh cycle, the card actively counts down). Most direct-merchant connections use live tokens. |
| Why expiry matters | A token that expires silently breaks all downstream Shippo cards: shipments stop incrementing, OTD freezes, claims show stale, costs flatline. The break is not visible until 24+ hours of zero data, which can hide for a weekend. |
| Polling cadence | Vortex IQ polls Shippo every 15 to 60 minutes for shipment / tracking data, but only refreshes the token-life check once per hour. Real-time accuracy is ±1 hour. |
| Renewal path | Live tokens: regenerate at Shippo App → Settings → API → Tokens, then update Vortex IQ at Settings → Connectors → Shippo → Reconnect. OAuth tokens: triggered by the partner re-auth flow, click “Reconnect” in Vortex IQ to refresh. |
| Permissions scope | The card reads only token expiry, not the token value itself. It cannot detect a token that is still valid but has been revoked manually in Shippo (revoked tokens fail at next API call; that surfaces in API Error Rate). |
| Q4 / peak risk | Token expiry during BFCM week is catastrophic: 24+ hours of blind shipment data during peak. The 14-day alert window gives time to re-issue before peak; aim for >30 days remaining on 1 November every year. |
| Time window | RT (real-time, refreshed hourly) |
| Alert trigger | <14 days, fires when remaining life drops below two weeks. |
| Roles | owner, operations |
Calculation
Calculated automatically from your Shippo data. See the At a glance summary above for what the metric tracks and the worked example below for a typical reading.Worked example
A US DTC accessories brand on Shopify. Shippo connector authorised on 12 Sep 25 with an OAuth-issued token (90-day rotation). Reading taken at 09:00 ET on 12 Mar 26.| Token attribute | Value |
|---|---|
| Token type | OAuth-issued (30-day refresh) |
| Issued at | 14 Feb 26 |
| Expires at | 16 Mar 26 |
| Days remaining (this card) | 4 |
<14 days tripped 10 days ago. Five things to notice:
- Four days is critical. A weekend (14 to 15 Mar) plus Monday-Tuesday gives roughly two business mornings to act before the token dies. Reconnect today.
- The card has been alerting since 02 Mar 26. If the merchant ignored the warn alert, downstream cards will start flatlining around 17 Mar 26: shipments stop incrementing, OTD freezes, claim count locks. The break is gradual and invisible without this card.
- OAuth tokens silently rotate, live tokens do not. The brand connected via Shippo’s OAuth partner flow (typical for Shopify-integrated install) and got a 30-day token. A direct connect via Shippo API key would have given a no-expiry token. Either is fine; only OAuth needs ongoing reconnect.
- The reconnect is one click in Vortex IQ. Settings → Connectors → Shippo → Reconnect. The merchant is redirected to Shippo, approves the re-auth, and Vortex IQ swaps in the new token. Total elapsed time ~30 seconds.
- Cross-reference with API Error Rate. If error rate has been climbing toward expiry, the token may be partially failing already (some endpoints fail before others). Reconnect resolves both.
Sibling cards merchants should reference together
Token expiry is an operational-health card. Pair it with these to confirm overall connector health:| Card | Why pair it with Token Expiry | What the combination tells you |
|---|---|---|
| API Error Rate | Error rate climbs as token nears expiry on some endpoints. | If error rate climbs and expiry is near, reconnect first; the rate clears. |
| Label Generation Success | A failing token blocks label generation. | A label-success drop concurrent with low expiry days = token issue, not Shippo platform issue. |
| Shipments | Volume drops to zero after token death. | If shipments flatline at zero and expiry days were not heeded, token has expired. Reconnect first. |
Cross-connector: any other connector’s *_auth_token_expiry_days | Pattern. | Workspaces sometimes have a fleet of OAuth-bound integrations expiring on the same date if all were authorised at the same time. Stagger renewals on next round. |
Reconciling against the vendor’s own dashboard
Where to look in Shippo’s own dashboard: Shippo App → Settings → API → API Tokens. Each token row shows issue date, last used timestamp, and expiry (where applicable). The Vortex IQ Shippo token will be tagged with the partner-app identifier or shows as the merchant’s named live token. Why our number may legitimately differ from Shippo’s view:| Reason | Direction | Why |
|---|---|---|
| Polling cadence | Ours up to 60 minutes stale | Token-life check refreshes hourly. Shippo’s own UI is real-time. |
| OAuth refresh in-flight | Either | If Shippo issued a refresh token in the last hour, the card may show the old expiry until next poll. |
| Time zone | None practical | The card uses UTC days remaining; Shippo’s UI uses merchant zone. The day-count rounds the same way on both. |
| Manual revocation | Card cannot detect | A token revoked manually in Shippo without the corresponding workspace re-auth in Vortex IQ shows the old expiry until next API call fails. |
*_auth_token_expiry_days cards on every connector that exposes a refreshable token (BigCommerce, Shopify Partner App, GA4, Google Ads, Klaviyo, etc.). If multiple are nearing expiry simultaneously, that is usually because they were all authorised at the same time during onboarding.