At a glance
Days remaining until the merchant’s Japan Post API authentication token expires. When the token expires, every label and manifest call, every tracking lookup, and every claim-status query stops working until the merchant re-authenticates. The card reads in real time and alerts at 14 days remaining so the despatch team has time to renew before the cliff rather than discovering it at the counter on a Monday morning.
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 and homeware brand based in Osaka, around 3,200 outbound parcels per week, roughly 80 percent Yu-Pack domestic and 20 percent EMS for overseas orders. Reading taken at 09:30 JST on 12 Apr 26.
The card reads 5 days (it always surfaces the nearest expiry, which is the production token). The
<7 days critical band is tripped. Five things to notice:
- This reading should already have a ticket against it. The warn alert fires at
<14 days, so operations was first notified around 03 Apr 26. The escalation to paged on-call lands at<3 days, which is 14 Apr 26. The window to act calmly is closing: renew today, do not wait for the page. - The renewal window is open right now, so this is a 30-second job. Japan Post supports refresh-token flow inside the 30-day pre-expiry window, which this token entered on 18 Mar 26. Invoking the refresh endpoint extends the token by a further 90 days with no portal login, no MFA, no account-team involvement. Letting it lapse converts a 30-second engineering task into a multi-step re-authentication.
- The cost of letting it expire is operational, not theoretical. At 3,200 weekly parcels the brand despatches roughly 530 a day. A 6-hour outage during business hours blocks around 130 outbound shipments. Each blocked parcel ages into a despatch-SLA miss, and for the Yu-Pack Cool chilled SKUs the brand ships, a blocked label can mean a missed refrigerated collection slot and product spoilage.
- Worst case is a weekend expiry. If the token expires at 17 Apr 26 23:59 JST (a Friday), and the underlying credentials need account-team verification to re-issue, the team may not recover the connection until Monday. That is roughly 48 hours and around 900 blocked shipments, plus the recovery backlog.
- The sandbox token at 15 days is fine. Sandbox tokens are shorter-lived but low-impact: if one expires, only pre-production testing breaks. Treat that alert as informational, never paged. The real-world pattern to aim for is an automated refresh job (cron, Cloud Scheduler, Lambda EventBridge) that renews every 30 to 45 days. If this card ever drops below 30 days, your automation is broken; that is a higher-priority signal than the token itself.
Sibling cards merchants should reference together
Token expiry is the leading integration-health signal. Pair it with the cards that show the downstream blast radius:Reconciling against the source
Where to look in Japan Post’s own tooling: Japan Post Business Customer Portal then API Settings / Developer Console (API管理). The view shows the production token’s issued-at and expires-at timestamps in JST, plus a refresh control. Sandbox tokens are managed under a separate developer subdomain. English-language reference exists for the EMS endpoints; the broader API documentation is JP-language primary. The closest like-for-like view is the production token’s expires-at timestamp. Convert it to days-remaining against the current JST clock and it should match the card to within one day. Scan and event timestamps elsewhere in the Japan Post APIs are reported in carrier-local time (JST), so all of this maths is in the same time zone at source; Vortex IQ stores in UTC internally and converts back for display. Why our number may legitimately differ from Japan Post’s portal:
Cross-connector reconciliation:
This card has no carrier-side counterpart (token health is an integration concept, not a parcel concept), but the pattern is shared across every authenticated connector. The right view is “all carrier and payment integration health on one panel” so a single token lapse never becomes a single point of failure.
Known limitations / merchant FAQs
The alert fired at 14 days. Do I have to act now? Not this minute, but plan to act within 7 days. The 14-day threshold is a deliberate buffer; a token at 14 days can be refreshed at any time. The escalation path is: warn at 14 days (informational ticket), action ticket at 7 days, paged on-call at 3 days. If you run a scheduled refresh job, the 14-day alert is really a check that the job is healthy; if it fired, the automation may have skipped a run, so fix that first. What actually happens when the token expires? Every Japan Post API call returns401 Unauthorized immediately. In operational order of pain: (1) label and manifest generation fails, so the warehouse cannot print Yu-Pack, Yu-Pack Cool, EMS, or Letter Pack labels for new orders; (2) tracking-status pulls stop, so the customer-facing tracking page goes stale; (3) claim-status queries fail, so the claims team is blind; (4) cost and invoice data stops updating in Vortex IQ. Severity is highest at (1): despatch productivity for Japan Post-routed orders drops to zero until the token is renewed.
How long does re-authentication take?
A token still inside the renewal window: about 30 seconds via the refresh endpoint. An already-expired token with valid credentials: roughly 10 minutes (portal login plus MFA plus token re-issue). A token where the underlying account needs verification, which can happen for enterprise contract customers, can take 4 to 24 business hours, and longer over a weekend or Japanese public holiday.
Can I disable the alert if I have automated refresh in place?
Reconsider rather than disable. The better pattern is to leave the alert active and add a second, earlier alert at <45 days that surfaces “the automated refresh did not run on schedule” well before the standard 14-day threshold. Disabling the safety net entirely means a broken cron job goes unnoticed until the cliff.
My token expired over a weekend and the warehouse was blocked on Monday. How do I prevent that?
Three layered defences. (a) Run automated refresh on a schedule that does not depend on a human being awake (cron, Cloud Scheduler, EventBridge). (b) Keep the <14 days alert so a manual fix is possible during business hours. (c) Document the manual renewal steps in your runbook, including the Japan Post account-team emergency contact, so on-call engineers can recover outside business hours. Note that Japan Post account-team support is itself JST business-hours, so a Friday-evening expiry is the highest-risk scenario.
My multi-region brand runs separate Japan Post accounts per market. One card or many?
By default the card reads the nearest-to-expiry token across all connected accounts, so it is one card showing the soonest cliff. To monitor each account separately, connect each as its own connector profile in Vortex IQ; each then produces its own card. For most merchants the nearest-expiry view is enough because all accounts should share a renewal cadence.
The card says 90 days remaining but the API still returned 401. Why?
Three usual causes. (a) An account-credential change on the Japan Post side: the token is technically valid but the underlying account permissions changed (a contract amendment, a payment dispute, a password rotation). Check the portal for account-level notices. (b) Token revocation, which Japan Post can do outside the natural expiry, usually for a security event. (c) Rate limiting, which can produce 401-like responses under aggressive call volume; check API Error Rate for a parallel spike.
Why is the expiry 90 days and not longer?
Japan Post’s 90-day default balances operational stability against credential-rotation security: longer tokens reduce friction but widen the window if a credential leaks. Some mature enterprise contracts negotiate 180-day tokens; ask your Japan Post account team. Whatever the agreed lifetime, the card reads the real expires-at value, so a negotiated 180-day token is reflected accurately.