Shopline JWTs are long-lived (Phillipstoys’ is good until 2027-07) but silent expiry breaks order downloads. Surface before merchants notice.
At a glance
Health check on the Shopline JWT used to access the Orders, Products, and Inventory APIs. Shopline JWTs are typically long-lived (1 to 2 years) but expire silently with no merchant-side warning. When they expire, the dashboard goes blind and ops only finds out when a buyer complains. This card surfaces it before that moment.
| What it counts | Two signals combined: (1) JWT expiry timestamp from the token’s exp claim minus current UTC = days remaining, (2) consecutive auth failure count from the last polling window. Either signal triggers the alert. |
| API endpoint | The token is verified against GET /v1/store_info every poll cycle (5 minutes). A 401 / 403 response increments the auth-failure counter; a successful response resets it. |
| JWT signal | JWT.exp - NOW() measured in days. When this drops below 30 days, the alert fires; this gives the merchant time to refresh credentials before live API calls start failing. |
| Auth failure signal | Three consecutive failed polls (15 minutes total) trigger the alert independently of expiry. This catches credential-rotation events the merchant may not have planned for (e.g. Shopline rotating signing keys after a security incident). |
| What is logged | Every successful poll resets the counter; every failure logs the HTTP status, response body excerpt, and timestamp for engineering investigation. |
| Currency / tax | Not relevant; this is a connector-health card, not a financial card. |
| Time window | RT (real-time, every 5 minutes). |
| Alert trigger | JWT exp < 30 days OR auth failures > 3 consecutive. Hero-tier; this card has direct revenue-protection value because every other Shopline card depends on this token working. |
| Roles | owner, operations, engineering. |
Calculation
Calculated automatically from your Shopline data. See the At a glance summary above for what the metric tracks and the worked example below for a typical reading.Worked example
An APAC fashion brand running a Hong Kong Shopline store, snapshot at 09:00 HKT on 27 Apr 26. The brand connected Shopline to Vortex IQ on 12 Jul 25 with a JWT issued by their Shopline tenancy admin valid for 24 months.| Metric | Value |
|---|---|
| JWT issued | 12 Jul 25 |
| JWT exp claim | 12 Jul 27 |
| Days remaining | 442 |
| Last successful poll | 27 Apr 26 08:55 HKT |
| Consecutive auth failures | 0 |
| Alert state | Healthy |
| Metric | Value |
|---|---|
| Days remaining | 30 |
| Alert state | Yellow (approaching expiry) |
| Scenario | Without this card | With this card |
|---|---|---|
| Token expires Saturday at 03:00 HKT | Sunday-traffic spike; revenue card shows zero; ops panics; spends 4 hours diagnosing what is “broken”; only on Monday does someone realise the token expired | Card was amber 30 days ago; renewal happened during a Tuesday afternoon; Saturday Sunday-traffic flows normally |
Sibling cards merchants should reference together
| Card | Why it matters next to token health | What the combination tells you |
|---|---|---|
| Revenue Drop Alert | Downstream symptom. | If revenue drops to zero and token health is amber/red, the cause is the token, not real demand. |
| Total Revenue | What stops working. | Every Shopline financial card depends on this token; one expiry blanks them all. |
| Unfulfilled Orders | Operational impact. | If token expires, ops cannot see new orders; SLA breaches follow within hours. |
| Inventory Alerts | Stock visibility. | Inventory drift compounds when sync stops; this card protects against that. |
| Shopline Health Score | Composite. | Token health is a binary input to the health score; expired token forces it red regardless of other signals. |
| Other Auth Token cards across connectors | Cross-connector pattern. | Every connector has the same archetype card; agencies running multi-platform clients should keep them all green. |
Reconciling against the vendor’s own dashboard
Where to look in Shopline’s own dashboard:Shopline Tenancy Admin -> Settings -> Developer / API access -> Tokens Shows issued tokens with their expiry dates. The Vortex IQ token will be one of them, identifiable by name (typically “Vortex IQ Integration”).Shopline does not surface “days remaining” prominently anywhere; this card exists because the platform’s own UX assumes tokens are managed by an engineer who already knows when they will expire. Why our number may legitimately differ from Shopline’s Admin:
| Reason | Direction | Why |
|---|---|---|
| JWT exp claim accuracy | Identical | The JWT’s exp field is the authoritative source; we read it directly. The Admin UI displays the same value. No real divergence possible. |
| Auth failure detection | Vortex IQ-only | Shopline does not surface “consecutive auth failures from Vortex IQ” anywhere; this is a Vortex IQ-side signal only. |
| Time zone for “days remaining” | Marginal | We use UTC for the day-count; Shopline displays in store-local time. The difference is at most a few hours, not days. |
| Token rotation events | Either | If the merchant rotates the token in Shopline Admin without updating Vortex IQ, this card flips red within 15 minutes; Shopline Admin shows the new token immediately. |
shopline_alert_token_expiry.status = (jwt.exp - now < 30 days) OR (consecutive_failures >= 3). No reconciliation needed; the JWT exp claim is the source of truth.
Known limitations / merchant FAQs
Why does Shopline issue 1 to 2 year JWTs in the first place? Shopline’s API design assumes integrations are run by engineers who manage credentials proactively. The long token life is a convenience for engineers; the silent-expiry failure mode is a known UX gap that this card patches. My token expires next month; what happens at expiry? At expiry, every Shopline API call returns 401 Unauthorized. Vortex IQ stops receiving data; revenue, orders, fulfilment, inventory cards all freeze on their last-known values. The merchant typically does not notice until they wonder why “today” is empty on the dashboard. How do I renew my Shopline JWT? Log into your Shopline tenancy admin, navigate to Settings > Developer / API access > Tokens, generate a new JWT scoped to the same permissions, and paste it into Vortex IQ’s connector settings. Takes about 10 minutes total. The card says “auth failures >3 consecutive” but my token is not expired. What is happening? Three usual causes. (1) Shopline rotated their signing key after a security event; you need to re-issue your JWT. (2) Your store’s API access was disabled in tenancy admin (rare; usually a permissions cleanup gone wrong). (3) Network or DNS issue between us and Shopline; usually self-resolves within an hour. The drill-down view shows the failure HTTP code which narrows the cause. Can I extend the token’s life? Not without re-issuing it. Shopline JWTs have hard-coded expiry; the only way to extend is to issue a new one with a freshexp claim.
Why is the alert at 30 days out, not 7 days?
Because token renewal often requires the tenancy admin (a different person from the merchant operator) to act, and that person may take 1 to 2 weeks to respond. 30 days gives a comfortable runway.
Does this card protect against API rate-limit errors?
No. Rate-limit errors return 429, not 401/403, and they do not increment the auth-failure counter. They are surfaced separately under connector-health monitoring.
Why are Shopline tokens different from Shopify or BigCommerce?
Shopify and BigCommerce use OAuth with refresh tokens, so a refresh failure is a different signal. Shopline issues a static JWT at integration time and assumes manual rotation. The card adapts to the connector’s auth model; the user-facing semantic is the same: “is this connector going to work tomorrow?”.
Can I get notified at 60 days instead of 30?
Yes; the threshold is configurable in the manifest. Engineering-managed accounts often set 60 or 90 days for ample lead time.
Phillipstoys’ token expires 2027-07; why is the card showing “healthy” today?
Because Phillipstoys’ JWT was issued in mid-2025 with a 2-year life, leaving over a year of remaining validity. This is the textbook healthy state; the card stays green until 30 days before expiry, at which point it flips amber.