epic: API plan-limit upgrade lifecycle — detect → notify → self-serve upgrade (no auto-charge, no silent throttle)

[koala73]

Problem

API customers who exceed their plan caps have no consent-based path today. We cannot auto-move them to a pricier plan (that charges them without consent), and there's no way to notify them or let them self-serve upgrade. So the only current outcomes are bad: silently throttle them (once #3199 enforcement flips on) or surprise-charge them. The right lifecycle: detect → notify → offer self-serve upgrade → customer upgrades OR reduces traffic (their choice).

Surfaced concretely: the #3199 shadow-audit found 3 active api_starter customers steadily over their caps (e.g. user_3CUolmnQ at 268/min·4,016/day) — Business-scale usage on a Starter plan — with no way to move them up short of a manual, non-consensual Dodo-dashboard edit.

Lifecycle / children

1. Detect + notify (#NOTIF) — spot accounts approaching/over caps from usage telemetry (wm_api_usage / fix(api): P1 — enforce per-tier API limits (Phase 1: per-account burst + usage meter + safety ceiling) #3199 meter) and email/in-app them with an upgrade CTA. No silent throttle, no auto-charge.
2. Self-serve upgrade mechanism (gap: no self-serve plan upgrade/change flow for existing subscribers (Starter→Business; blocks #3199 enforce + misses revenue) #4634) — the "way to upgrade" the notification points to (Dodo portal plan-switch, in-app upgrade, or checkout-upgrade).
3. Self-limit — a first-class valid outcome; just needs honest messaging (usage vs cap), no build.

Relationship to existing work

• fix(api): P1 — enforce per-tier API limits (Phase 1: per-account burst + usage meter + safety ceiling) #3199 (per-tier rate limits, shadow) — this lifecycle is the humane layer that must exist before enforcement hard-429s anyone. Notify + offer upgrade first; enforce is the backstop.
• epic: usage-based overage billing on Dodo (Phase 2 of #3199) #4560 (usage-based overage billing) — notify→upgrade is the pre-billing consent path; if/when overage billing ships, the same detection powers "you're in overage" messaging.

Product decisions to resolve in planning (ce-brainstorm)

• Notification thresholds (80% / 100% / sustained-over-burst) and spike-vs-sustained logic.
• Channels (email, in-app, both) + cadence / anti-spam.
• Upgrade UX: Dodo portal plan-switch vs in-app upgrade vs self-serve checkout (and whether to make Business self-serve).
• Sequencing: does this gate the fix(api): P1 — enforce per-tier API limits (Phase 1: per-account burst + usage meter + safety ceiling) #3199 enforce flip? How does it hand off to epic: usage-based overage billing on Dodo (Phase 2 of #3199) #4560 overage billing?
• Copy / tone for over-limit + upgrade + self-limit-is-fine messaging.

Definition of done (epic)

A customer who crosses their plan caps is notified with a clear, honest message and a working self-serve path to upgrade — and can equally choose to reduce traffic — with no auto-charge and no silent throttle. This unblocks the #3199 enforce flip.

[koala73]

Children: #4634 (self-serve upgrade mechanism), #4636 (detect + notify). Related: #3199 (enforce — this precedes it), #4560 (overage billing — this is the consent on-ramp).

[koala73]

Requirements (from ce-brainstorm 2026-07-02): docs/plans/2026-07-02-001-feat-api-plan-limit-upgrade-lifecycle-plan.md.

Resolved scope: growth/upsell feature that gates the #3199 enforce flip. v1 = (1) near-limit warn+upsell, (2) in-app upgrade flow via Dodo subscription-change/proration, (3) informative at-cap 429 (upgrade CTA, never a bare 'Too many requests'); self-limit is a valid choice. Flip API_RATE_LIMIT_ENFORCE=true only after all three are live. Overage billing (#4560) deferred; auto-charge/auto-move explicitly rejected. Key open blocker: Dodo subscription-change/proration API availability (OQ1) — resolve in ce-plan.

[koala73]

Implementation-ready plan landed (via ce-brainstorm→ce-plan→ce-doc-review): docs/plans/2026-07-02-001-feat-api-plan-limit-upgrade-lifecycle-plan.md

5 units, ready for /ce-work. Unit→issue map: #4634 = U1 (Dodo change-plan action + edge) + U2 (in-app upgrade UI); #4636 = U3 (near/over-cap detection + notification); U4 (informative at-cap 429) + U5 (#3199 sold-cap daily enforcement) extend #3199.

Doc review drove a product decision (folded in): the daily axis will hard-enforce at the sold allowance (429 at 1,000/day for Starter), not #3199's current 10× ceiling — mirrors how per-minute already enforces at 60/min, and makes 'warn + informative at-cap limit' coherent (added U5). Warn on BOTH axes (per-minute burst + daily). All U1–U5 must-fixes (IDOR, target allowlist, charge idempotency, changePlan-is-void→webhook, previewChangePlan for cost, Convex→Upstash detection, plan_key hoist) are captured in the plan's Review Findings section. To /ce-work later: ce-work docs/plans/2026-07-02-001-feat-api-plan-limit-upgrade-lifecycle-plan.md.

[koala73]

Status update — U3 delivered by PR #4648 (codex), reviewed vs plan: KEEP-with-6-fixes (see #4648 + #4636). It's the notify half only. Remaining build: U1+U2 (self-serve upgrade/charge, #4634), U4 (informative 429), U5 (#3199 sold-cap enforcement). #4648's Starter→Business CTA currently mailto's support because the self-serve upgrade flow (U1/U2) doesn't exist yet — wire it to U2 when built. Enforce flip stays gated on U4/U5 + fixed #4648 all live.