Skip to main content
Metrics type: Key Metrics • Category: Shipping & Courier

​
At a glance

Days until your ShipTheory API auth token expires. ShipTheory uses an OAuth bearer model with typical 365-day token windows; when the token expires, label-print, rate-shop and tracking calls fail immediately, breaking despatch end-to-end until a human re-authenticates. The card is the operational early-warning system; the alert at <14 days gives change-management cushion.

​
Calculation

Calculated automatically from your ShipTheory 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 UK home & garden merchant. Reading taken at 09:00 GMT on 12 Mar 26. The card reads 2 days for the main UK workspace; the alert at <14 days has been firing for 12 days. Five things to notice:
  1. The clock has been counting down for 363 days; nobody noticed for 351 of them. Failure mode of token-expiry: silent until catastrophic. The alert is meant to guarantee humans notice with two weeks cushion. If acknowledged but deprioritised, escalate now.
  2. Two days is a Friday-evening risk. If the token expires Saturday 03:00 GMT (original issue timestamp), Saturday morning despatch breaks. Monday’s despatch will face a backlog of unprocessed orders from Saturday and Sunday. Rotate today.
  3. The eu workspace is healthy and is the rollback path. Cross-region label printing is technically feasible from the eu workspace but requires manual override; document the path before rotating.
  4. Re-auth requires a human in ShipTheory’s UI. OAuth flow needs an admin to log into ShipTheory Account → API Settings, generate new token, copy bearer, paste into Vortex IQ connector. Total time <5 minutes pre-staged; coordinate with despatch downtime.
  5. After rotation, card resets to 365 days. Re-read 24 hours after rotation to confirm new expiry has propagated; if the card still shows <14 days, the new token did not save correctly. Record the rotation in workspace audit log.

​
Sibling cards merchants should reference together

Token-expiry is binary at day-level (alert fires or not), but a leading indicator for a chain of operational cards.

​
Reconciling against the vendor’s own dashboard

Where to look in ShipTheory’s own dashboard: ShipTheory Account → API Settings. The page lists the active token, issue date, expiry date, and a “Generate New Token” action. Numbers should match the card exactly (card and portal read same source). Variance >5 minutes = stale poll cycle; manual reconnect refreshes. Why our number may legitimately differ from ShipTheory’s portal: Cross-connector reconciliation:

​
Known limitations / merchant FAQs

Why does ShipTheory use expiring tokens? Security policy. ShipTheory’s OAuth model rotates the bearer to limit credential-leak exposure. Standard tokens are 365-day; enterprise can request shorter (180/90). Trade-off: shorter window = more rotation work, smaller blast radius. The token expired and despatch is broken. Recovery time? Mechanical rotation: 5 to 10 minutes if you have ShipTheory admin access ready. Connector resumes API calls within one poll cycle (5 to 15 minutes). Backlog re-queues. Total restoration ~30 minutes; longer if you wait for an admin user. Can I rotate proactively? Yes, recommended. ShipTheory lets you generate a new token before the old expires; both valid simultaneously for grace period. Rotate at the 30-day mark on calendared cadence, not in firefighting mode. Why 14-day alert specifically? Convention across cloud-platform secret rotation. Two business weeks is enough cushion for change-management approval and rollback. Below 7 days = P2; below 2 days = P1. Multi-workspace, separate rotation each? Yes, each workspace has its own token; rotate independently. Build a calendar that staggers them. What happens to in-flight shipments when token expires? Already-printed labels continue tracking via carrier webhooks. Visible breakage is on new shipments: cannot rate-shop, cannot print labels, cannot file claims. Can I automate token rotation? Partially. ShipTheory’s API supports programmatic re-issue once OAuth client is authorised. A workspace can run a quarterly script that issues new token, posts to Vortex IQ, revokes old. The OAuth handshake still needs annual re-authorisation. My token says “never expires” but the card shows a number? Some legacy ShipTheory accounts have non-expiring tokens. The connector falls back to a synthetic 365-day display from issue date; this is a placeholder and will not actually expire. Set the alert to “ignore” for those accounts.

​
Tracked live in Vortex IQ Nerve Centre

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