Plan & Usage (your plan, your allowance, your credit)

What it is

Settings → Accounts & AI → Plan & Usage. The ONE customer-facing money screen, organized by what a user actually does: see the plan they're on and this month's AI allowance, see and top up their prepaid credit balance, compare Free vs Pro and upgrade or manage ($15/mo Pro via Stripe), and bring their own API key. (A per-seat Team card exists but is held dark until the gateway's Team price is wired — see below.)

Renamed from "Plan & Billing" and expanded on 2026-08-18: it absorbed the credit balance + Buy-Credit (previously buried under Settings → API Keys) and replaced the separate mock Pricing screen, so there is now exactly ONE place to pay. Subscriptions and one-off credit top-ups are still separate money paths with separate Stripe webhooks that never cross — see stripe-credit-topups.md for the credit path.

Where to find it

Settings → Accounts & AI → Plan & Usage. It is the only storefront in the app; the upgrade prompt a free user meets routes here.

How it behaves

What the user sees

• Your plan — the current tier (Free / Pro / a comped tier), read from their Global Auth claim.
• Monthly allowance meter — how much of the month's pooled-AI allowance is used, and when it resets (first instant of the next UTC month). Fetched on open only, never polled (cost). If the tier has no configured cap the meter hides and says the allowance isn't set up yet; at/over a real cap it clamps to 100% rather than showing a nonsense number. As of 2026-08-25 the per-plan pooled-AI allowance is $0 on every tier (owner decision — no free company-funded AI budget on any plan): general in-app AI declines and falls back to the user's own key / prepaid credit. With a $0 allowance the meter hides entirely and simply says AI runs on your own key or prepaid credit — a zero allowance is not an exhausted one, so there is no bar and no warning. (Until 2026-09-03 this rendered a maxed-out 100% bar and told everyone — paying Pro and Team subscribers included — that they had used up an allowance they never had.) When a real positive cap IS configured and genuinely runs out, the warning is tier-aware: only a Free user is pointed at Pro; a paid subscriber is pointed at prepaid credit or their own key. Two safety-net features (the inbound-email security screen + the Ask-Omniscio keyless help) still run on the shared company pool, exempted from the per-user cap in the gateway — everything else is user-paid. This screen is also where the "built-in AI helpers stopped" inbox card sends the user — it is the one place that answers both halves of that card (how much you get + how to keep going, whether by upgrading or pasting your own key). See built-in-ai-helpers.md for the per-tier numbers and the two card variants. the one place that answers what that card leaves open (how to keep going, whether by upgrading or pasting your own key). See built-in-ai-helpers.md for the two card variants.
• Credit balance + Buy Credit — the prepaid gateway credit, shown right under the allowance so "what's left" (this month's allowance AND your credit) sits in one place. Top up with a card via Stripe ($10 / $25 / $50 / $100 presets, or a custom $5–$1,000). The same balance still appears under Settings → API Keys (creating a pooled key needs it), now with a link back here to add credit. The balance + Buy-Credit UI is one shared component so both screens stay identical. The balance can read negative, and it is shown that way on purpose (e.g. -$0.50) with the note "from usage overage — your next top-up covers it". A charge is reserved as an estimate and settled at the real cost, so a balance can dip slightly below zero; it is small, bounded, and the next top-up absorbs it. (Until 2026-09-03 a negative balance displayed as $0.00 — a real debt hidden behind a reassuring zero.)
• Free vs Pro — a plain comparison so the upgrade decision needs no docs. The refund policy is linked right here on the money screen, next to Manage/cancel.
• Upgrade to Pro — visible only when the user is signed in AND on Free. A paid or comped tier hides it, so nobody is ever invited to buy something they already have.
• Team (per-seat) card — hidden by default. It shows a seat picker and a live $25/seat total, but the gateway has no Team price wired yet, so an "Upgrade to Team" click would fail with "not available". Since 2026-09-03 the card sits behind its own in-development flag (team-subscription) and is revealed as part of Team go-live, together with the gateway price — never before it. A storefront that cannot take the money does not show the price.
• Manage or cancel subscription — visible only to an actual Pro/Team subscriber. Opens the Stripe Billing Portal where they can cancel, update their card, or view invoices. A Free user has nothing to manage, so they never see it.
  • The portal does not accept refund requests. Stripe's Customer Portal exposes no refund-request action; what it can show is a link to the refund policy, and only if that is configured owner-side in the Stripe dashboard's Customer Portal settings. Refund requests go to legal@omniscio.com per the published Refund & Cancellation Policy. Do not tell a customer to request a refund in the portal — there is nothing there to click.
• Bring your own API key (BYOK) — use a personal provider key instead of the pooled allowance.

How the upgrade actually works

1. The button calls the gateway (POST /v1/subscription/checkout) and opens the returned Stripe hosted Checkout URL in the browser. Card details never enter Omniscio.
2. The gateway pins client_reference_id to the verified Firebase uid server-side — never a value the client supplies. This is the load-bearing security property: the webhook trusts that field to decide whose account gets Pro, so a client-settable value would let a signature-valid checkout name any victim.
3. A separate Firebase webhook (stripeSubscriptionWebhook) receives the verified Stripe event and flips the user's tier claim free → pro. Cancel or lapse flips it back.
4. The tier claim is what the gateway reads to grant the larger pooled-AI monthly allowance.

Because the grant happens on a verified webhook and not on the browser returning, closing the tab or a flaky network can't leave someone paid-but-not-upgraded.

Monthly or annual (2026-09-08)

Pro is sold on two intervals, which is what the Terms advertise: $15/month, or $144/year — about 20% off. The Pro card carries a Monthly / Yearly toggle and shows the saving next to it.

A few things that are true and non-obvious:

• The screen never states the discount as a fixed number. It divides the two prices and rounds. If Pro is ever repriced, the percentage moves with it instead of quietly contradicting the Terms, and a build-failing guard reads the published Terms document and turns red if the code and the legal text ever disagree.
• The choice only appears once the annual price is actually live (the pro-annual-billing flag, revealed alongside the Stripe price id). Before that the card is monthly-only, because a priced offer nobody can buy is worse than no offer at all.
• The interval you pick is what the gateway charges against. It is validated on the way through; an unrecognised value is rejected rather than quietly billed as monthly. It changes what is billed, never who — the account charged is always the verified signed-in user.
• Both Pro prices grant the same Pro. The webhook maps the monthly and the annual price id to the same tier, so an annual buyer is entitled exactly like a monthly one.

The annual renewal reminder (2026-09-08)

The Terms promise: "For any annual (one-year) plan, we will send a renewal reminder before the renewal charge." A daily job does this.

• It emails an annual subscriber 30 days before the charge, once per period.
• It never emails after the charge has happened — a notice that arrives afterwards is not a reminder, so a renewal date already in the past is out of range by construction.
• It skips anyone who is already cancelling (nothing renews), anyone on monthly (the promise is annual-only), and anyone whose payment is retrying after a failure (that is dunning, not a clean renewal — telling them "you will be charged on the 14th" would be wrong).
• It sends first and records second, deliberately. If recording fails, the worst case is a duplicate reminder next day; the alternative failure — marking someone as reminded when the email never went — would breach a published promise silently.
• Every run logs what it scanned, sent and skipped, so a quiet month and a broken job do not look identical.

How manage / cancel works (2026-08-17)

The Manage or cancel subscription button calls the gateway (POST /v1/billing-portal) and opens the returned Stripe Billing Portal URL in the browser. Same load-bearing security property as checkout: the gateway resolves the Stripe customer SERVER-SIDE from the verified Firebase uid's users/{uid}.stripeCustomerId — never a value the client supplies — so a signed-in user can only ever open their own portal. Cancelling flows back through the same verified stripeSubscriptionWebhook that a subscribe does (it flips the tier), so the button never changes the plan itself. The refund terms (14-day, less consumed AI credits) live in the public Refund & Cancellation Policy. The portal is where a customer cancels, updates a card, and pulls invoices — it does not accept a refund request (Stripe's Customer Portal has no such action); the policy routes those to legal@omniscio.com.

Go-live (owner): the portal needs the gateway deployed AND Stripe's Customer Portal activated in the Stripe dashboard. Until then the route 503s and the button surfaces a friendly "not available" rather than a dead action.

Behaviour worth knowing

• A failed card keeps Pro for Stripe's retry window (~3 weeks, past_due → pro) — a deliberate dunning grace so one expired card doesn't instantly cut off a paying customer. Bounded by the Pro monthly allowance, so it can't be abused.
• A full refund of a subscription charge revokes Pro back to Free. When Stripe reports a subscription charge fully refunded (charge.refunded), the webhook downgrades the tier to free, so a refund can't leave someone holding a paid month's AI allowance for free. A partial refund and a one-time credit top-up refund never touch the plan. (Needs the webhook endpoint subscribed to charge.refunded; chargebacks are covered by Stripe's dispute→cancel automation — see the subscription-tier contract's go-live steps.)
• A subscription never overwrites an admin-granted tier. It owns the free↔pro↔team axis (ManagedTier = 'free' | 'pro' | 'team'); an enterprise grant is left alone in both directions. So a Team subscriber's plan IS subscription-managed — only enterprise is admin territory. (The retired starter tier no longer exists; the ladder is free < pro < team < enterprise.)
• If the gateway has no Pro price configured, the button surfaces a friendly "not available" rather than a dead checkout, and credit top-ups keep working untouched.

Company-funded AI is a Pro perk (2026-08-15)

The "extra" (non-Claude) AI services that spend Omniscio's OWN keys are Pro-only for signed-in users, except where noted below — voices moved to metering on 2026-09-02 and the API-key gateway opened in August. Free and anonymous users always keep their own-key (BYOK) and free on-device options:

• Gated now: GLM company credits and cloud speech-to-text.
• Metered, not gated (2026-09-02): company read-aloud/narration voices (Fish + Soniox) are no longer Pro-only. Any signed-in user can use them; each synthesis spends their plan's monthly voice time first, then their prepaid credit, and only a user with neither is stopped — with a top-up/upgrade prompt, never a message about an API key they never entered. Included voice time per month: Free $0 · Pro ~$3.75 (about 5 hours) · Team & Enterprise ~$7.50 per seat (about 10 hours). A free account therefore runs entirely on credit. Bringing your own voice key removes the metering altogether. Voice has its own budget line, deliberately separate from the company-AI allowance below, which stays $0 on every plan.
• Open to any signed-in user (2026-08-24): the API-key credits gateway — minting + using a personal jls_sk_ key. The Pro paywall on minting was removed for adoption; spend is still prepaid-gated (a $0 balance blocks minting + declines calls, fail-closed). The managed proxy lanes CrofAI / DeepInfra / GLM keep their own Pro gate; DeepSeek was opened to all signed-in users too (2026-08-25), so free users with credit can call it as well. OpenRouter company-credit sessions — running any model OpenRouter serves (~400) on the company key — are likewise open to any signed-in user with credit (2026-08-27), priced live at the standard 10% markup.
• Still free for everyone: bringing your own voice/provider key, and on-device voice (local Whisper) — never gated.
• Wired but open: the inbound-email safety pre-screen and the in-app help fallback are Pro-capable but left ON for everyone today (flippable later, no redeploy).
• Reach: applies to signed-in users on the multi-user/cloud deployment; a plain single-user install runs as the operator and keeps everything (the operator is never restricted on their own machine). That "keeps everything" is a DESKTOP promise only. A service running on Omniscio's servers — a relay, the credits gateway — sees a plan, not an operator, so it cannot honour it. Where a surface has a server-side check, the server decides. This bit a real user on 2026-09-02: a single-user install was told locally that company voices were allowed, the server refused for not being Pro, and the app relayed that as "check your Fish Audio API key" — for a key they had never entered. Voice now meters instead, so it needs no operator exception at all.

A free signed-in user who hits one of these sees an Upgrade to Pro prompt instead of a dead button. Enforced app-side + (for GLM) server-side; the remaining server-side backstops are a tracked follow-up. Detail: .claude/memory/contracts/company-funded-ai-paywall-contract.md.

Related

Related

• Contract: .claude/memory/contracts/plan-billing-storefront-contract.md
• Contract: .claude/memory/contracts/stripe-subscription-tier-contract.md (the webhook that flips the tier)
• stripe-credit-topups.md — the separate one-off credit path