Days to Token Expiry, Shippo

Metrics type: Key Metrics • Category: Shipping & Courier

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

The card reads 4 with the alert at <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.

Cross-connector reconciliation: There is no cross-platform reconciliation for this card; token-life is a per-integration concern. The card pairs with similar *_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.

Known limitations / merchant FAQs

My Shippo connector was a Live API token; the card always showed ”-”. Now it shows 30 days. What changed? Shippo or your team likely re-authorised via the partner OAuth flow (often during a Shopify app reinstall), which swaps the no-expiry live token for a 30-day OAuth token. The integration still works the same; it now needs a reconnect every 30 days. To revert to live-token behaviour, generate a new live token in Shippo and paste into the Vortex IQ connector config. The card shows 0 days but Shippo data is still flowing. Why? Two possibilities. (1) Polling lag. Vortex IQ caches the token-life check for an hour; the latest reconnect is in flight. Force-refresh the connector to re-read. (2) Token was just renewed but the workspace hasn’t yet picked up the new metadata. Wait one polling cycle. Should I rotate during BFCM peak? No. Rotate at least 30 days before BFCM and at least 14 days after. A failed rotation during peak loses 24+ hours of shipment visibility, which on the November-December window means hundreds to thousands of consignments untracked. What if I miss the alert and the token expires? Three immediate steps. (1) Reconnect via Settings → Connectors → Shippo → Reconnect (one click). (2) Wait 5 to 10 minutes for the connector to back-fill missed shipments and tracking events from the gap window. (3) Verify Shipments is incrementing again and API Error Rate has cleared. Total recovery time is typically under 30 minutes. Do live tokens ever silently revoke without expiry? Rarely, but yes. Shippo support occasionally rotates tokens for security reasons (e.g. credential reuse detected on a different device). If shipments suddenly flatline with the card showing ”-” or 365+ days, the token has been revoked manually, reconnect to refresh. Why doesn’t Shippo email me when the token is about to expire? Shippo does send a notification for OAuth tokens at 7 days; many merchants have notification emails turned off or routed to a no-longer-monitored shared inbox. The Vortex IQ card is the redundant surface specifically because email-based renewal reminders are unreliable. My agency rotates tokens for me. How do I confirm it’s done? Watch the card. After agency reconnect, the card should reset to the new full-window remaining (typically 30 or 365 days). If the card still shows the pre-renewal countdown 1 hour after the agency confirms, the token wasn’t actually rotated.

Tracked live in Vortex IQ Nerve Centre

Days to Token Expiry is one of hundreds of KPI pulses Vortex IQ tracks across Shippo 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.

Get Started

The AI OS

At a glance

Calculation

Worked example

Sibling cards merchants should reference together

Reconciling against the vendor’s own dashboard

Known limitations / merchant FAQs

Tracked live in Vortex IQ Nerve Centre

​At a glance

​Calculation

​Worked example

​Sibling cards merchants should reference together

​Reconciling against the vendor’s own dashboard

​Known limitations / merchant FAQs

​Tracked live in Vortex IQ Nerve Centre

At a glance

Calculation

Worked example

Sibling cards merchants should reference together

Reconciling against the vendor’s own dashboard

Known limitations / merchant FAQs

Tracked live in Vortex IQ Nerve Centre