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

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 / #3199 meter) and email/in-app them with an upgrade CTA. No silent throttle, no auto-charge.
2. Self-serve upgrade mechanism (#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

• #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.
• #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 #3199 enforce flip? How does it hand off to #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.

Start by reading the wm_api_usage telemetry and #3199 meter work, then review child issues #NOTIF and #4634. Resolve the notification thresholds, channels, upgrade path, sequencing, and copy before implementation; done means customers receive an honest upgrade option or can reduce traffic without auto-charge or silent throttling.