Billing & Entitlement Assurance

Reconcile Stripe, credits, subscription entitlements, webhook replay safety, plan gates, and admin repairs

Billing & Entitlement Assurance

Billing & Entitlement Assurance is the V4 closeout control plane for Stripe, credits, subscription access, webhook replay, plan gates, and repair operations.

What It Checks

  • Credit reconciliation: compares each user's current balance with the latest credit ledger balance_after value and detects ledger sequence gaps.
  • Entitlement drift: flags paid local plans without Stripe customers, FREE users receiving subscription grants, and stale paid subscriptions without recent invoice-backed renewal credits.
  • Webhook replay safety: verifies Stripe ledger rows have webhook idempotency records and detects duplicate credit-bearing events, payment intents, and invoice grants.
  • Plan gates: validates premium and team-only feature access rules so FREE, PRO, and TEAM entitlements do not silently drift.
  • Revenue anomalies: surfaces purchases without payment intents, subscription grants without invoice IDs, unusually large credit movements, and non-admin unlimited-credit accounts.

Admin API

GET /api/admin/billing-assurance?periodDays=45

Returns the assurance report for admins and super admins. The report includes:

  • score and severity summary
  • checked users, transactions, and webhook events
  • failed plan gates
  • revenue-impacting issues
  • repairable issue count
  • trust guardrails

POST /api/admin/billing-assurance

Applies a repairable issue with an audit row:

{
  "issueId": "credit-balance:user_123",
  "reason": "Reconciled after Stripe webhook replay review"
}

Automated repairs are intentionally narrow:

  • sync a user credit balance to the latest authoritative ledger row
  • downgrade a paid local entitlement to FREE when no Stripe customer exists
  • disable unlimited credits for non-admin users
  • backfill a missing Stripe webhook idempotency record before replay

Alerting

Revenue-impacting critical and error findings emit operational alerts through the existing monitoring pipeline. Alerts are deduped by the issue set for one hour.

Release Guardrails

  • Stripe Billing and Checkout remain the source of truth for paid subscriptions.
  • Credit repairs create credit_transactions audit rows; balances are not silently changed.
  • Webhook replays should not run until event ID, invoice ID, and payment intent idempotency are clean.
  • Plan-gating regressions are release blockers.