Context

Following #3116 (user-facing API key management), this issue tracks adding usage-based metered billing so API call volume can be charged beyond flat-rate plan limits.

What exists today

• Flat-rate subscription plans via Dodo (Free, Pro, API Starter, API Business, Enterprise)
• Entitlements with apiRateLimit values per tier (0 / 60 / 300 / 1000 req/min) — stored but not enforced
• Dodo SDK installed (dodopayments npm package) — includes usage-events resource, currently unused
• Dodo webhook pipeline (signature-verified, idempotent) handling subscription lifecycle events
• IP-based rate limiting via Upstash Redis sliding window

What's needed

Metering infrastructure

• Per-user API call counter (Redis or Convex) — increment on each authenticated API request
• Rolling window or daily/monthly aggregation
• Report usage events to Dodo via their usage-events API

Dodo configuration

• Create metered product(s) in Dodo dashboard
• Configure pricing tiers / overage rates
• Wire up usage reporting from our backend to Dodo

Enforcement

• Enforce apiRateLimit per user-key (depends on feat(auth): user-facing API key management (create / list / revoke) #3116)
• Overage handling — hard cap vs. overage billing vs. throttling
• Usage alerts / notifications to users approaching limits

Frontend

• API usage dashboard — show current period usage, limits, history
• Usage alerts in the UI

Dependencies

• feat(auth): user-facing API key management (create / list / revoke) #3116 (API key management) — need per-user keys before we can meter per-user usage

Open questions

• Hard cap at plan limit vs. allow overage with per-call billing?
• Billing granularity — per request, per 1K requests, daily?
• Which endpoints are metered — all authenticated API calls, or only specific premium endpoints?

🤖 Generated with Claude Code