Days to Token Expiry, FedEx

Metrics type: Key Metrics • Category: Shipping & Courier

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.

The card reads 2 days with red sentiment. Three things to do, in order:

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.

Note: this card is one of two operational-health gauges shippers should track; the second is API Error Rate, which catches partial failures between rotation events (rate-limit hits, transient FedEx outages).

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.

Cross-connector reconciliation:

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.

Known limitations / merchant FAQs

Why does this card exist? Doesn’t FedEx auto-renew tokens? FedEx access tokens auto-refresh every hour using the refresh token. The refresh token / API client credential itself is what this card tracks; that one does not auto-renew. It must be regenerated manually in the FedEx Developer Portal at the end of its TTL (default 1 year). When it expires, every downstream FedEx call breaks. The card says 14 days but I rotated yesterday. Why? Likely a delay between portal rotation and Vortex IQ re-handshake. Open Vortex IQ Settings → Connectors → FedEx and click “Reconnect” with the new credential pair. The card refreshes hourly and updates within 1 to 2 hours of a successful re-auth. My credential expires in 30 days but I won’t be available to rotate it. What can I do? Two options. (1) Pre-rotate. Generate a new credential today, paste into Vortex IQ, and the card resets to ~365 days. There is no penalty for early rotation. (2) Delegate. Add a second admin to your FedEx Developer Portal account with rotation rights, and add a Vortex IQ workspace member with connector-edit rights. The handoff is a 2-step process either of you can complete. What if the credential expires while we’re shipping? Label printing breaks immediately on the next FedEx Ship Manager API call. The WMS will queue outbound orders. The Shopify or BigCommerce checkout still works (no impact to incoming orders). Recovery is to rotate the credential and trigger a manifest replay in the WMS; expect 2 to 6 hours of order-shipping delay for the queue to drain. Is there a way to set a longer TTL than 1 year? FedEx caps the maximum TTL at 1 year for security. Some enterprise contracts negotiate a 2-year TTL; ask your FedEx account team if you ship >$500K/year. For most merchants, the 1-year default is enforced; build the rotation into your annual operations calendar. What if I am running multiple FedEx accounts? Each Vortex IQ connector instance has its own credential and its own card reading. Multi-account setups (e.g. a US LLC and a Canadian subsidiary) typically need two connector instances. Watch both cards; expirations are independent. Do FedEx test-credentials and production-credentials use different countdowns? Yes. Test-environment (CXS sandbox) credentials default to 90 days; production credentials default to 365 days. The card reads whichever environment the connector is pointing at; the badge in Vortex IQ Settings → Connectors shows env=test or env=prod. Test-credential expirations do not affect live shipping but do break testing workflows.

Tracked live in Vortex IQ Nerve Centre

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