Billing Operations & Reconciliation
Billing Safety · BIL-10, BIL-18, BIL-24 · Priority: P1
Why This Cluster Matters
Your app's billing state and Stripe's billing state will inevitably drift. Webhooks fail, manual changes happen in the Stripe dashboard, payment retries succeed hours later. Without reconciliation, refund handling, and proper metered billing, your app silently loses revenue or grants access it shouldn't.
These 3 checks cover the operational side of billing — the processes that keep your app honest after the initial subscription is created.
Checks in This Cluster
| ID | Check | Priority |
|---|---|---|
| BIL-10 | Reconciliation mechanism | P1 |
| BIL-18 | Refund/dispute handling | P1 |
| BIL-24 | Metered billing usage | P2 |
BIL-10: Reconciliation Mechanism
Webhooks are not guaranteed to arrive. Stripe retries failed deliveries, but your server may have been down, or the webhook handler may have thrown an error after partially processing. Over time, your database drifts from Stripe's reality.
A reconciliation mechanism periodically compares your local subscription data with Stripe's API and fixes discrepancies. Without it, drift accumulates silently — users on canceled plans keep access, users who reactivated lose it.
What to verify: A scheduled job or on-demand process that fetches active subscriptions from Stripe and compares them against your local state. Discrepancies are logged and auto-corrected or flagged for manual review.
BIL-18: Refund/Dispute Handling
When a customer disputes a charge or you issue a refund, what happens in your app? AI tools never handle charge.refunded or charge.dispute.created webhooks. The customer gets their money back from Stripe, but your app still shows them as a paying customer with full access.
What to verify: Refund and dispute webhooks trigger appropriate state changes — downgrade, access revocation, or grace period. Disputes are logged for review. Repeated disputes trigger account flagging.
BIL-24: Metered Billing Usage
If your app charges based on usage (API calls, storage, AI tokens), usage must be reported to Stripe accurately and enforced server-side. AI tools often implement usage tracking on the client (easily manipulated) or fail to report usage to Stripe's metered billing API, resulting in customers never being charged for overages.
What to verify: Usage is tracked server-side, reported to Stripe via usage records API, and enforced before allowing the action (not just billed after the fact).
References
Related Checks
- Billing State Integrity — BIL-05, BIL-06, BIL-07
- Stripe Webhook Safety — BIL-02
Is your app safe? Run Free Scan →