Skip to main content

Billing Diagnostics runbook

Billing incidents need careful handling: protect money facts, preserve audit evidence, and verify recovery through APIs/read models before direct database inspection.

First Checks​

SymptomFirst checks
Billing worker failedWorker run status, billing window, policy values, ledger write errors
Balance appears wrongLedger-derived balance API, recent credits/debits, allocation usage window
Stripe webhook failedRaw-body signature verification, idempotency key, provider event status
App runtime charge missingApp/runtime attribution, allocation link, usage event or metering source
Auto-release surpriseLow-balance events, policy threshold, notification evidence, allocation state

Diagnostic Flow​

Operator Rules​

  • Do not update or delete ledger rows.
  • Do not replay a payment webhook without idempotency and provider-event checks.
  • Do not hand-compute balance as the source of truth.
  • Treat repeated direct SQL billing checks as missing operator surface.
  • Record refund, correction, and payment exceptions with owner, reason, expiry, and correlation ID.
Canonical sources