At a glance
Days remaining before the FedEx Web Services API OAuth credential the merchant uses to print labels, retrieve tracking, and pull billing data expires. A real-time operational health gauge. Below 14 days is amber; below 7 is red. At zero, label printing breaks and orders stop shipping.
| What it counts | (token_expires_at - now()) / 86400 rounded down to whole days. The card reads the FedEx OAuth refresh-token TTL stamped at the last successful auth handshake. |
| Token type | FedEx Developer Portal API uses OAuth 2.0 client-credentials. Access tokens last 1 hour and refresh automatically; the refresh token / API client credential is what this card tracks, with vendor-default 1-year lifetime, manually rotatable in the FedEx Developer Portal. |
| What “expired” actually breaks | Once the credential expires, POST /ship/v1/shipments returns HTTP 401 and label generation stops. Tracking-API reads (GET /track/v1/trackingnumbers) also fail, so the rest of the FedEx KPI surface in Vortex IQ goes stale. Outbound shipments queue at the WMS until labels can be printed. |
| Detection mechanism | Vortex IQ inspects the JWT/credential metadata returned at every token-refresh event. The expiry stamp is cached and decremented hourly. A failed refresh attempt (revoked credential, account suspension) is also treated as “expired now”. |
| Renewal path | FedEx Developer Portal → My Projects → [Project] → API Keys → Regenerate. Generates a new client_id + client_secret pair. The merchant must paste the new credentials into Vortex IQ Settings → Connectors → FedEx → Reconnect, which re-runs the OAuth handshake. Total downtime: typically under 5 minutes if done proactively; up to 24 hours if discovered post-expiry. |
| Notification cadence | The card alerts at <14 days (warn) and <7 days (critical). Vortex IQ also sends an in-app banner and email to the workspace owner at 14, 7, 3, and 1 day. |
| Multi-account merchants | Merchants with multiple FedEx account numbers under one developer project share a credential. Merchants with separate developer projects (e.g. a US account and a Canadian account) have separate credentials, each card reads only this connector instance’s token. |
| Time window | RT (real-time, refreshed hourly) |
| Alert trigger | <14 days (warn) / <7 days (critical) |
| Roles | owner, operations |
Calculation
Calculated automatically from your FedEx 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 home-goods merchant connected FedEx Web Services on 14 Mar 25 with a freshly issued client credential. Reading taken on 12 Mar 26.| Date | Days to expiry | Card state | What happened |
|---|---|---|---|
| 14 Mar 25 | 365 | green | Initial connection, credential rotated. |
| 14 Sep 25 | 181 | green | Mid-life, no action. |
| 14 Feb 26 | 28 | green | Approaching warn threshold. |
| 26 Feb 26 | 16 | green | First Vortex IQ pre-warn email to workspace owner. |
| 28 Feb 26 | 14 | amber | Warn alert tripped. Banner appears in Nerve Centre. |
| 07 Mar 26 | 7 | red | Critical alert. Daily email to workspace owner. |
| 12 Mar 26 | 2 | red | Reading at the time of this example. |
- Rotate the credential today, not tomorrow. Open the FedEx Developer Portal, regenerate the API key pair for the project, and paste the new client_id + client_secret into Vortex IQ Settings → Connectors → FedEx. Total downtime if done proactively: under 5 minutes. The label-print app keeps running through the swap because the access-token cache survives across credential rotation as long as Vortex IQ refreshes within the access-token’s 1-hour window.
- Schedule a recurring rotation reminder. FedEx credentials default to a 1-year lifetime. Add a calendar reminder for 11 months from today; do not rely on Vortex IQ alerts as your only safety net (email deliverability, holiday timing).
- If the credential expires before rotation, label printing breaks. The WMS will queue all outbound FedEx orders. Recovery: rotate the credential as in step 1, then trigger a manifest replay in the WMS to re-attempt all queued labels. Expect 2 to 6 hours of order-shipping delay; same-day cutoff orders for that day are usually missed.
Sibling cards merchants should reference together
Token expiry is a binary “is the connector still alive?” gauge. Pair it with these to see the full operational-health picture.| Card | Why pair it with Days to Token Expiry | What the combination tells you |
|---|---|---|
| API Error Rate | Catches partial failures between rotation events. | Expiry counts down deterministically; error-rate spikes flag transient FedEx outages, rate-limit overruns, and bad payload shapes. The two together cover both scheduled and unscheduled connector breakage. |
| Label Generation Success Rate | The downstream workload that breaks first when the token expires. | If label-success drops below 95% while token expiry is still green, the cause is rate-limits or payload errors, not auth. |
| Shipments Total | Volume context. | A sudden drop in shipments-total to zero, with token expiry at 0 days, confirms expiry is the cause. A drop with token still valid points elsewhere (WMS outage, label-app bug). |
Cross-connector: shopify.unfulfilled_orders | Downstream impact. | When labels stop printing, Shopify orders stack up unfulfilled. A spike in Shopify backlog co-occurring with FedEx expiry-at-zero is the unmistakable “we missed the rotation” signature. |
Reconciling against the vendor’s own dashboard
Where to look in FedEx’s own dashboard: FedEx Developer Portal → My Projects → [Project Name] → API Keys. The portal shows the credential-creation date and the configured TTL. FedEx does not surface a countdown gauge directly, so the card is the operational-friendly view of what the portal stores in raw form. Why our number may legitimately differ from FedEx’s portal:| Reason | Direction | Why |
|---|---|---|
| TTL configuration | Either | FedEx allows custom TTLs per project (default 1 year, configurable down to 30 days). The card reflects whatever TTL was set at credential issue; the portal shows the raw value. |
| Manual revocation | Card may show stale | If the merchant manually revokes the credential in the portal but does not reconnect Vortex IQ, the card continues to count down to the original expiry until the next failed refresh attempt. The first auth call after revocation surfaces the breakage. |
| Time zone | <1 day off | Credentials expire at a UTC instant; the card rounds to whole days in workspace local time. Display can drift by <1 day at boundary. |
| Card | Expected relationship | What causes legitimate divergence |
|---|---|---|
usps.usp_auth_token_expiry_days | Peer-carrier connector health. Independent credentials. | Different lifetime conventions; USPS web-tools credentials do not expire by default but can be revoked manually. |
easypost.eas_auth_token_expiry_days | Aggregator alternative. | EasyPost issues its own API key with no TTL, but the underlying carrier credentials still expire on EasyPost’s side and can break rate-shopping silently. |