At a glance
Days remaining until the merchant’s Japan Post API authentication token expires. When the token expires, every label-generation call, tracking lookup, and claim-status query stops working until the merchant re-authenticates. The card alerts at 14 days remaining to give operations time to renew before the cliff.
| What it counts | (token_expiry_timestamp - now) ÷ 86400 (seconds-to-days). The token is OAuth2-style, with a typical lifetime of 90 days for production credentials. |
| Delivery success criterion | n/a, this is an integration-health metric, not an operational metric. |
| On-time threshold | n/a. |
| Returns / RTO | n/a. |
| Service level scope | n/a. The token is account-wide; one token covers Yu-Pack, Yu-Pack Cool, EMS, Letter Pack, and the Tracking and Claims APIs. |
| Currency | n/a. |
| Token type | Japan Post issues two separate token classes: (a) production tokens (90-day lifetime, refreshable up to 30 days before expiry), (b) sandbox / staging tokens (30-day lifetime, separate credentials). The card defaults to production; sandbox tokens are not surfaced unless explicitly connected. |
| Refresh behaviour | Japan Post supports refresh-token flow; the merchant can renew the token any time within the 30-day pre-expiry window. After expiry, full re-authentication is required (manual portal login, MFA challenge, contract verification by Japan Post account team for some enterprise tiers). |
| Multi-environment merchants | A merchant with separate production and sandbox accounts has two tokens; the card surfaces the nearest expiry across all connected accounts. |
| Time window | RT (real-time, computed on every card refresh) |
| Alert trigger | <14 days, escalating to critical at <7 days. Tokens at <3 days should trigger a paged alert. |
| Roles | owner, operations |
Calculation
Calculated automatically from your Japan Post 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 Japanese-headquartered DTC apparel brand based in Osaka, ~3,200 outbound parcels per week. Reading at 09:30 JST on 12 Apr 26.| Token | Issued | Expiry | Days remaining | Status |
|---|---|---|---|---|
| Production (primary) | 17 Jan 26 | 17 Apr 26 | 5 days | CRITICAL |
| Sandbox (test environment) | 28 Mar 26 | 27 Apr 26 | 15 days | OK |
- The production token has 5 days remaining and is in the critical band. The card alerts at
<14 days; this reading should have triggered an action ticket roughly 9 days ago. The alert escalates to paged-on-call at<3 days. Operations needs to renew TODAY; if the token expires at 17 Apr 26 23:59 JST, every label-generation call after that timestamp will return401 Unauthorizedand warehouse operations will halt. - The renewal window is open right now. Japan Post supports refresh-token flow during the 30-day pre-expiry window; this token entered the renewal window on 18 Mar 26. The simplest action is to invoke the refresh-token endpoint, which extends the token by another 90 days without requiring re-authentication. This is a 30-second engineering task.
- The cost of letting the token expire is meaningful. At 3,200 weekly parcels, even a 6-hour outage during business hours blocks ~120 outbound shipments. Each blocked shipment ages into a customer-experience issue and (for time-sensitive Yu-Pack Cool refrigerated SKUs) into spoilage. Worst case: token expires Friday evening, full re-authentication requires Japan Post account team support which is unavailable until Monday morning, ~48 hours of downtime, 900+ blocked shipments.
- The sandbox token at 15 days is fine. Sandbox tokens are shorter-lived (30 days) but lower-impact; if a sandbox token expires the only effect is that pre-production testing breaks until renewed. Treat the alert priority as informational, not paged.
- The right operational pattern is automated refresh. Most enterprise Japan Post integrations should be running a scheduled job (cron, Cloud Scheduler, etc.) that refreshes the token every 30 to 45 days, well before the alert fires. If this card ever drops below 30 days, the automated refresh is broken; treat that as a higher-priority signal than the token itself.
Sibling cards merchants should reference together
| Card | Why pair it with Days to Token Expiry |
|---|---|
| API Error Rate | The downstream signal. When the token expires, every API call returns 401; API error rate spikes immediately. The two cards are complementary: token-expiry is the leading indicator, API error rate is the lagging confirmation. |
| Label Generation Success | The most operationally critical API call. Token expiry causes label-generation failure first; the card’s success rate drops to 0% on token death. |
| Total Shipments | The downstream impact. Token outage blocks new label generation; shipment volume drops to zero hours into an outage. |
| Cross-connector: any other carrier connector with auth tokens (Royal Mail, USPS, etc.) | Same pattern, same operational priority. Treat token-expiry across all shipping carriers as a single class of integration-health signal. |
| Cross-connector: payment-gateway auth tokens (Stripe, PayPal) | Same shape, different impact. Payment-gateway token expiry blocks revenue collection rather than fulfilment; the operational impact is faster and harder. |
Reconciling against the vendor’s own dashboard
Where to look in Japan Post’s own portal: Japan Post Business Customer Portal → API Settings / Developer Console (API管理). The view shows token issued-at and expiry-at timestamps, plus a refresh button for the production token. Sandbox tokens are managed via a separate developer subdomain. For the Japan Post API documentation including OAuth flow, refer to the developer reference (Japan Post developer portal, JP-language primary; English documentation is available for EMS endpoints only). Why our number may legitimately differ from Japan Post’s portal:| Reason | Direction | Why |
|---|---|---|
| Time-zone (JST vs UTC) | Boundary days | The token expiry timestamp is stored in JST natively; Vortex IQ converts to UTC for the days-remaining calculation. For the most part this affects only sub-day precision. |
| Refresh latency | Vortex IQ slightly stale | When a refresh-token call extends the expiry, Vortex IQ picks up the new expiry on the next API health-check (typically every 5 to 15 minutes); the portal updates immediately. |
| Account-tier differences | Either | Enterprise contract customers sometimes have longer-lived tokens (180 days) negotiated as part of the contract; the card reads whatever Japan Post returns in the token metadata. |
| Multi-account merchants | Vortex IQ shows the nearest-expiry across all connected accounts | The portal shows per-account; reconcile by checking each account separately. |
| Sandbox vs production conflation | Possible | Default to production; if the connected credential is a sandbox token by mistake, the card surfaces it but the operational impact is different. |
| Card | Expected relationship | Why |
|---|---|---|
royal_mail.roy_auth_token_expiry_days | Same shape, different network | Royal Mail’s API uses a different token lifecycle (typically 60-day with auto-refresh on every call), so the same merchant’s two tokens won’t co-expire. |
fedex.fedex_oauth_expiry | Same shape | FedEx OAuth is short-lived (1-hour bearer tokens, refresh-on-demand); the days-remaining concept doesn’t apply. |
stripe.stripe_secret_key_status | Same operational priority, different mechanism | Stripe API keys do not expire by default but can be rotated; treat both as “integration secrets” requiring monitoring. |
Known limitations / merchant FAQs
The alert fired at 14 days. Do I have to act now? Not immediately, but plan to act within 7 days. The 14-day threshold is set deliberately to give operations a buffer; tokens at 14 days remaining can be refreshed at any time. The escalation path: alert at 14 days (informational ticket), at 7 days (action ticket), at 3 days (paged on-call). If you have a scheduled refresh job, the 14-day alert is a check that the job is healthy; if the job is broken and you act manually now, you have 14 days to fix the automation before the next renewal. What happens when the token actually expires? Every Japan Post API call returns401 Unauthorized immediately. Concrete impact in operational order: (1) Label-generation calls fail, the warehouse cannot print Yu-Pack / EMS labels for new orders. (2) Tracking-status updates stop pulling, customer-facing tracking page goes stale. (3) Claim-status queries fail, claims-team cannot check status. (4) Cost / invoice data stops updating in Vortex IQ. The operational severity is highest at #1; warehouse productivity drops to zero for Japan Post-routed shipments until the token is renewed.
How long does re-authentication take?
For a still-within-the-renewal-window token: 30 seconds via the refresh-token API call. For an expired token: 10 minutes if the merchant credentials are valid (manual portal login + MFA + re-issue token). For a token where the underlying account credentials need verification (e.g. enterprise contract customers needing Japan Post account team approval): 4 to 24 business hours during normal hours, longer over weekends.
Can I disable the alert if I have automated refresh in place?
Possibly, but reconsider. The right pattern is to leave the alert active and tune it to fire only when automation breaks. If automated refresh runs every 30 days, set a separate alert at <45 days to surface “automation didn’t run on schedule” before the regular 14-day threshold fires. Don’t disable the safety net.
My token expired over a weekend and operations was blocked Monday morning. How do I prevent this?
Three layered defences. (a) Run automated refresh on a schedule that doesn’t depend on humans (cron / Cloud Scheduler / Lambda EventBridge). (b) Set the alert at <14 days so manual intervention is possible during business hours. (c) Document the manual renewal procedure in your runbook so on-call engineers can act outside business hours, including the Japan Post account team contact for emergency re-issue.
My multi-region brand has separate Japan Post accounts for different markets. Do I get one card or many?
The card reads the nearest-to-expiry token across all connected accounts. To monitor each account separately, configure each as a distinct connector in Vortex IQ; each will produce its own card. For most merchants the nearest-expiry view is sufficient because all accounts should be on the same renewal cadence.
The token says 90 days remaining but the API still returned 401. Why?
Three usual causes. (a) Account-credential change at Japan Post side. Token is technically valid but the underlying account permissions changed (e.g. a contract amendment, payment dispute, password rotation). Check the Japan Post portal for any account-level notifications. (b) Token revocation. Japan Post can revoke a token outside the natural expiry (rare, usually for security incidents on Japan Post’s side or detected unauthorised use of the token). (c) Rate limiting. Hitting the API too aggressively can produce 401-like errors; check API Error Rate for parallel symptoms.
Why is the expiry 90 days and not longer?
Japan Post’s security model uses 90-day tokens as a reasonable balance between operational stability and credential-rotation security. Longer tokens reduce operational friction but expand the attack window if a token is leaked; shorter tokens force more frequent rotation but improve security posture. The 90-day default is industry-typical for high-trust integrations. Some Japan Post enterprise contracts negotiate 180-day tokens for very mature customers; ask your Japan Post account team if needed.