billing-economics-source

Billing economics source

Problem this handles

Companion bills users by deducting credits from a usage ledger. A real failure mode is treating UI display math as a second billing model, or spreading markup between worker rates, UI money helpers, Autumn config, and scripts. When the user asks "global 1.25x" or "how does pricing work," answer the source-of-truth model first, then edit.

Subscription price changes have a second failure mode: treating Autumn or the repo constants as the only truth layer after native iOS billing is in scope. A request like "fix all pricing" means web and Apple purchase rails, not only the provider surfaced by the first stale CLI output.

Activation boundary

Load when changing any of these:

• CREDIT_MARKUP, provider raw-cost to credit conversion, or "global 1.25x / 1.5x" pricing behavior.
• src/lib/billing/economics.ts, src/lib/billing/money.ts, worker billing rates, usage ledger writes, billing retry/reconcile scripts, or Autumn credit item values.
• Plan subscription prices, monthly/annual plan amount changes, RevenueCat product/package/entitlement mapping, App Store Connect subscription price schedules, or paywall/store product price displays, including annual savings badges.
• Usage UI, chat credit footer, billing usage tables, or any display that shows credits consumed from usage_events.costMicroCents.

Near-misses:

• Per-plan caps, quotas, storage, vCPU/RAM, or sandbox templates: use tiered-plan-limits.
• Pricing page copy or plan-card marketing without changing billing facts: use product-surface-polish.

Procedure

1. Before editing, state the current model with evidence. For usage economics: raw provider cost is marked up into ledger micro-cents; ledger micro-cents are deducted as credits; UI displays ledger credits. For subscription prices: preserve the user's term for the truth layer and list every rail you will verify before claiming the fix.
2. Read the live source path, not memory:
   • src/lib/billing/economics.ts
   • src/lib/billing/constants.ts
   • workers/agent/lib/billing/rates.ts
   • workers/agent/lib/billing/usage-service.ts
   • autumn.config.ts
   • src/lib/billing/money.ts
   • workers/app/services/usage.ts
   • iOS billing/paywall source and product ID mappings when Apple billing is in scope
   • any UI component or script touched by the requested change
3. Keep the source of truth narrow:
   • CREDIT_MARKUP, ledger unit constants, and credit price constants belong in src/lib/billing/economics.ts.
   • Subscription target prices start in plan constants/config, but live charge truth is provider-specific: Autumn/Stripe for web, App Store Connect for Apple subscriptions, and RevenueCat for product, entitlement, package, and webhook mapping.
   • Apply provider limits at the smallest plan/period scope the evidence proves. An App Store price-point or product-status limit on Max annual disables or changes Max annual only; do not remove annual choices from Plus/Pro or rewrite other rails unless their own records fail the same check.
   • For RevenueCat-backed mobile billing, Autumn receives RevenueCat updates; Autumn prices do not decide the mobile charge.
   • Worker billing code imports economics helpers and writes already-marked-up usage_events.costMicroCents.
   • Autumn tracking uses the same ledger value converted to credits.
   • UI money helpers format ledger values; they must not define markup or estimate raw provider cost unless the surface is explicitly internal and labeled as raw provider cost.
4. For annual price or savings-badge changes, write the arithmetic table before editing: monthly price x 12 baseline, live provider candidate annual prices, exact savings percentage, displayed badge, and the user's rounding rule. "Round percentage" means integer percentage unless the user names another increment; do not invent 5% steps, "conservative" labels, or a lower savings badge when the stated goal is to show the best deal. If no exact common candidate exists across plans, say that before recommending a business fallback.
5. Resolve provider contradictions before mutating. Do not push a catalog or patch code from a summary table when detailed JSON, dashboard UI, or the charge provider disagrees.
6. Delete duplicate economics constants instead of syncing them by comment. Prefer imports from src/lib/billing/economics.ts across server, scripts, Autumn config, tests, and UI.
7. If a raw-cost reporting surface is genuinely needed, name it as raw provider cost and keep it separate from user credit consumption.
8. Add focused guards for the drift you changed:
   • rate tests for markup and raw-dollar conversion;
   • money tests for ledger credit formatting;
   • usage tests for costMicroCents to Autumn credit value;
   • grep guard that no second CREDIT_MARKUP definition or raw-cost display helper remains in the UI layer.
   • for subscription prices, capture the exact provider records checked: Autumn detailed product records, RevenueCat products/offerings/entitlements, and App Store Connect subscription status plus storefront price schedules.