credit-metering

Credit metering

Build credits as a financial state machine. Preserve existing denominations, billing semantics, and provider integrations.

Workflow

1. Inspect backend/runtime, database/ORM, auth and tenant keys, current balance/ledger fields, payment provider, usage paths, retries, queues, and frontend state.
2. Infer existing costs, grants, and packs from code. Ask only for unresolved commercial policy: denomination, per-action or measured cost, free/recurring grants, expiration/rollover, refund/clawback behavior, and overspend/debt policy. Never default to a new payment provider when one exists.
3. Read database schemas, then implement only the matching database variant. Do not treat PostgreSQL, MySQL, Prisma providers, and MongoDB as interchangeable. PlanetScale runs both Vitess (MySQL) and Postgres: detect the engine before choosing. Write migrations that can run twice.
4. Use an append-only ledger with a unique idempotency key/external event ID. Update cached balance and ledger in one database transaction, or derive balance from the ledger when scale permits. Enforce positive input amounts and the chosen non-negative/debt rule in the database.
5. Implement explicit operations:
   • grant for signup, subscription, promotion, or admin credit;
   • reserve before costly/concurrent work;
   • capture after measured success;
   • release on cancellation/failure;
   • refund or reverse linked to the original transaction;
   • expire/rollover when credits have lifecycle rules.
6. Authenticate and authorize from server context. Never accept balance, price, pack value, or user identity from the browser. Map a server-owned product/price ID to the credit amount.
7. Read payment providers only for the detected provider, or for provider choice on a new build. Its facts carry a check date; re-check any older than 90 days before relying on it. On Lemon Squeezy, check its status and flag the Stripe Managed Payments migration path; do not start a new build on it by default. If the provider offers native credits (Dodo credit entitlements, Stripe credit grants), name one balance source of truth and keep gating usage in the app. Verify raw-body signatures, durably deduplicate events, and retry transient failures. Acknowledge before processing only after a durable queue/inbox write.
8. Make promotions atomic. Use a redemption table with a unique (promo_id, user_id) constraint when one redemption per user is intended; update global usage and grant credit in the same transaction.
9. Treat the UI balance as a projection. Reconcile after responses, account switches, multi-tab updates, refunds, and webhook grants. Optimistic display must not authorize work.