Billing Assurance Runbook

Triage credit drift, Stripe replay safety, entitlement repairs, and billing assurance alerts

Billing & Entitlement Assurance Runbook

Use this runbook when credits, subscription access, Stripe webhooks, or plan gates look wrong.

1. Generate A Report

Open the admin assurance endpoint:

curl -sS "$NEXT_PUBLIC_APP_URL/api/admin/billing-assurance?periodDays=45"

Review:

  • summary.status
  • summary.score
  • summary.alertCount
  • issues[].category
  • issues[].repair

2. Triage By Severity

  • critical: stop billing-related deploys until the issue is repaired or explained.
  • error: repair before replaying Stripe events or changing entitlements.
  • warning: review during the current billing operations window.
  • info: use as context.

3. Safe Repairs

Only use POST /api/admin/billing-assurance for repairable issues. Each repair creates an audit trail:

  • balance syncs create a credit transaction with the delta
  • entitlement downgrades create a subscription audit row
  • unlimited-credit changes create a zero-amount audit row
  • webhook backfills create an idempotency record

Do not directly edit user balances or subscription tiers in the database unless this API is unavailable and an incident commander approves the manual change.

4. Stripe Replay Checklist

Before replaying any Stripe event:

  • confirm stripe_webhook_events.event_id is present or intentionally absent
  • confirm duplicate stripe_event_id rows did not grant credits more than once
  • confirm duplicate stripe_payment_intent_id rows did not credit purchases twice
  • confirm duplicate stripe_invoice_id rows did not grant subscription credits twice
  • confirm the user's local tier matches the Stripe subscription state

5. Closeout

After repair:

  • regenerate the report
  • confirm summary.alertCount is zero or every remaining alert has an incident note
  • confirm plan gates still pass
  • keep the operational alert fingerprint in the incident log when one was emitted