At a glance
Live count of days remaining until the Amazon SP-API LWA refresh-token (or carrier-side credentials) expires. Amazon Prime Shipping connector reads from the Amazon Selling Partner API for SFP shipment metadata and from each connected carrier’s API for tracking events. When credentials expire, label generation stops, tracking webhooks stop, SFP eligibility scoring may be impacted by data gaps. The card is the early-warning trip-wire.
| What it counts | floor((credential_expires_at - now) / 86400) in days. |
| Credential type | Amazon SP-API uses Login-with-Amazon (LWA) refresh tokens with a 1-year lifetime when properly configured. Carriers (UPS, USPS, OnTrac) have separate API keys with carrier-specific lifetimes (typically 1 year for UPS/OnTrac; USPS Web Tools key has no formal expiry but requires periodic refresh). |
| What expiry means | Without SP-API access, Vortex IQ cannot read SFP shipment metadata. Without carrier API access, tracking webhooks and label generation halt. The merchant cannot dispatch new Prime-promised orders until credentials are restored. |
| Auto-refresh behaviour | Amazon SP-API refresh tokens auto-rotate access tokens silently on each call. Refresh token itself can persist for 1 year; merchant action only needed when refresh token age exceeds Amazon’s reset trigger (rare). Carrier API keys typically require manual rotation. |
| Service level scope | Connector-wide. SFP and Buy with Prime equally affected. |
| Currency | N/A |
| B2B vs B2C | N/A |
| Time window | RT |
| Alert trigger | <14 days. |
| Roles | owner, operations |
Calculation
Calculated automatically from your Amazon Prime Shipping (SFP) 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 merchant connected Amazon SP-API on 14 May 25 with a UPS API key and OnTrac key issued at the same time. Reading taken at 09:00 ET on 30 Apr 26.| Credential | Issued | Expires | Days remaining |
|---|---|---|---|
| Amazon SP-API LWA refresh token | 14 May 25 | 14 May 26 | 14 |
| UPS API key | 14 May 25 | 14 May 26 | 14 |
| OnTrac API key | 14 May 25 | 14 May 26 | 14 |
| USPS Web Tools key | 14 May 25 | (no formal expiry) | n/a |
| Amazon Logistics (in-Seller-Central) | 14 May 25 | (managed by Amazon) | n/a |
- Multiple expiries on the same day. Coordinated rotation week is more efficient than three separate rotations. Plan for 1 to 2 hours total.
- SP-API is the most consequential. Without SP-API, Vortex IQ loses visibility into SFP shipments entirely; the dashboard goes dark for this connector.
- Carrier rotations are independent processes. UPS rotation in UPS Developer Kit; OnTrac rotation in OnTrac account portal. Each carrier has its own URL and credential UI.
- USPS Web Tools doesn’t formally expire but Amazon-side requires periodic re-auth (every 6 months typically) for SFP-eligible USPS Priority labels. Worth refreshing alongside the others as a hygiene step.
- Amazon Logistics credentials are Amazon-managed. No merchant-side rotation needed; access flows through your Amazon Seller Central session token.
Sibling cards merchants should reference together
Token expiry is connector-health early-warning. Pair with these:| Card | Why pair it with Days to Token Expiry | What the combination tells you |
|---|---|---|
| Label Generation Success | First operational symptom. | If both red, rotation may have failed. |
| API Error Rate | 401/403 spikes when token mid-rotation. | Spike + expiry imminent = new credential not propagated. |
| Shipments | Volume drops to zero on expiry. | Catastrophic outcome the 14-day alert is to prevent. |
Cross-connector: amazon.amazon_auth_token_expiry | Amazon connector SP-API token. Same credential. | Track once at the Amazon connector level if running both. |
Reconciling against the vendor’s own dashboard
Where to look: Amazon SP-API: Seller Central → Develop Apps → My Apps. Carriers: each carrier portal (UPS Developer Kit, OnTrac account, USPS Web Tools). Why our number may legitimately differ:| Reason | Direction | Why |
|---|---|---|
| Multi-credential | N/A | Card reads the most-imminent expiry across SP-API + carrier credentials. |
| Auto-refresh | N/A | SP-API access tokens auto-refresh; the underlying refresh-token expiry is what this card surfaces. |
| Card | Expected relationship | What causes legitimate divergence |
|---|---|---|
amazon.amazon_auth_token_expiry | Same SP-API token. | Track once. |
Known limitations / merchant FAQs
SP-API LWA refresh token: when does it actually expire? Amazon SP-API LWA refresh tokens are valid until the user revokes the app authorisation, the seller account is closed, or 1 year of inactivity passes. In practice, well-functioning integrations renew automatically through normal API calls. The 14-day-warning surfaces the ~1-year mark as a hygiene checkpoint. Carrier API credential rotation: who handles it? The merchant. Carrier portals require account-owner login. UPS in UPS Developer Kit, OnTrac in OnTrac account portal, USPS Web Tools at usps.com/business/web-tools-apis. Each takes 5 to 15 minutes individually. What happens if SP-API access fails? Vortex IQ loses visibility of new SFP shipments. Existing data persists; the card shows historic data but stops updating with new orders. Recovery: re-authorise the SP-API connection in Vortex IQ connector settings. Why does the alert fire at 14 days? Operational realism: gives ops a clean two-week window to coordinate rotations across SP-API + 3-4 carriers without dispatch disruption. Multi-marketplace SP-API: how does it work? Amazon SP-API issues one refresh token per Selling Partner; that token works across marketplaces (US, CA, MX). For European or other regional marketplaces, separate authorisation may be required. The card reads the connected credential. Q4 peak: should we rotate early? Yes. Rotating credentials in October gives a clean buffer for November-December peak. The cost of an SP-API outage during peak is catastrophic (label generation halts, SFP eligibility data gaps). Buy with Prime: does this card cover that too? Buy with Prime uses different credential infrastructure (Buy with Prime API). If the merchant has Buy with Prime connected separately, that credential’s expiry shows on a separate connector dashboard. This card surfaces SFP-side credentials. Carrier-side credential expiry: most consequential? UPS is most. UPS handles the largest share of SFP volume on most US merchants; UPS API outage = label-generation halt for the East Coast / Midwest cohort. USPS less consequential because rural-USPS volume is smaller and the credential is more permissive. Auto-refresh edge cases? Refresh-token rotation can fail silently if the merchant changed their Amazon login email, enabled MFA on the SP-API client, or revoked the developer app authorisation. The 14-day warning is the surface signal; investigateama_api_error_rate for ongoing 401/403 events.
Coordinated multi-credential rotation: best practice?
Schedule one weekday daytime slot (Tuesday 10am-12pm typical). Open all four portals (Amazon, UPS, OnTrac, USPS). Rotate each in sequence, paste new credential into Vortex IQ connector after each. End-to-end ~90 minutes. Verify by sending a test SFP label after all rotations.