[Feature]: display provider-reported subscription / plan renewal dates in Providers #1060

Area

Web Dashboard → Providers / account metadata

Problem

OpenCodex currently exposes operational account information such as quota/rate-limit state and reset timing, but users may also need to know when a paid subscription, token plan, or account entitlement actually expires or renews.

These are different concepts.

In particular, this issue must not treat OAuth/access-token expiration as subscription expiration.

OAuth credentials may expire and refresh while the user's underlying subscription remains active. Displaying that timestamp as "subscription expires" or "plan renews" would be misleading.

Goal

Where a provider exposes authoritative subscription or entitlement metadata, surface that information in the Providers dashboard.

Examples of useful provider-reported fields include:

Plan renews: Aug 25, 2026
Subscription expires: Sep 1, 2026
Billing period ends: Aug 31, 2026
Entitlement valid until: Aug 20, 2026

The exact terminology should follow what the provider's source actually represents.

Data-source requirement

A displayed subscription/plan date must come from a source that actually represents the provider's subscription, entitlement, billing period, or plan validity.

Acceptable sources may include:

• an authenticated provider account/subscription API;
• provider quota metadata that explicitly includes plan renewal or entitlement expiry;
• account metadata returned by an official provider endpoint;
• an equivalent provider-native source with documented semantics.

Do not infer a plan date from:

• OAuth access-token expiry;
• OAuth refresh-token expiry;
• API-key expiration;
• session expiration;
• quota reset time;
• rate-limit reset time;
• arbitrary credential-file timestamps.

If a provider does not expose trustworthy plan metadata, OpenCodex should simply omit this field for that provider.

Provider capability

Support should be capability-driven rather than assuming that every provider exposes the same metadata.

A provider/account may expose zero or more concepts such as:

quotaResetAt
billingPeriodEndsAt
planRenewsAt
subscriptionExpiresAt
entitlementExpiresAt

The implementation does not need to manufacture a single universal timestamp when the upstream semantics differ.

Where possible, normalize provider-native metadata into a small typed OpenCodex account/subscription metadata contract while preserving the meaning of the source field.

Dashboard behavior

When authoritative metadata exists, show it alongside the corresponding provider/account in the Providers dashboard.

Examples:

Plan renews Aug 25, 2026
Subscription expires Sep 1, 2026
Billing period ends in 12 days

Requirements:

• display the correct semantic label;
• format dates using the active locale;
• handle unavailable/unknown metadata without warnings or fake placeholders;
• clearly distinguish plan/subscription timing from quota-reset timing;
• do not expose credential secrets or raw provider payloads.

Multi-account providers

For providers with multiple accounts, the metadata belongs to the individual account unless the provider explicitly defines it at a shared subscription level.

Do not copy one account's subscription date onto unrelated accounts merely because they use the same provider.

Previous implementation attempt

PR #1081 attempted part of this issue but was closed unmerged.

It exposed an existing OAuth/Codex credential expiresAt value and rendered it as account expiration.

That is not sufficient for this feature.

The maintainer review identified two separate problems:

1. the changed locale catalogs did not compile;
2. more importantly, the displayed value represented renewable OAuth token expiry rather than actual subscription/plan expiry.

Any future implementation should reuse only infrastructure that is semantically appropriate. Credential expiration and subscription expiration must remain distinct fields.

Suggested implementation order

For each supported provider:

1. identify an authoritative provider-native source for subscription/plan metadata;
2. document what each upstream timestamp means;
3. normalize that metadata into a safe management DTO;
4. add focused parsing/contract tests;
5. expose it in the Providers UI;
6. add localized presentation and GUI regression coverage.

Provider support can be delivered incrementally. One trustworthy provider is better than pretending all providers expose a common subscription date.

Out of scope

This issue does not require:

• calculating billing dates heuristically;
• scraping provider websites;
• treating rate-limit resets as subscription renewals;
• treating OAuth token expiry as plan expiry;
• implementing provider billing or payments;
• displaying sensitive credential metadata.

Acceptance criteria

• At least one provider has an authoritative subscription/plan metadata source.
• The source semantics are documented and tested.
• OAuth/access-token expiry remains distinct from subscription/plan expiry.
• Quota/rate-limit reset timestamps remain distinct from subscription/plan timing.
• Provider/account management DTOs expose only safe normalized metadata.
• The Providers dashboard displays the correct semantic label and localized date.
• Missing metadata is handled cleanly.
• Multi-account providers associate metadata with the correct account.
• No subscription date is fabricated when a provider does not expose one.
• Additional providers can add support without changing the basic UI/data contract.
• Accepted implementation is merged into dev.

Related work

• feat(providers): display account subscription / plan expiration date in dashboard (#1060) #1081 — closed, unmerged attempt that exposed credential expiry; useful as prior-art only, not as a correct data source for this feature.