Honest Invoicing — Reference

The main spec: problem, proposal, brain expansion, credit note implementation, and the plan.

Four handlers in billing-webhooks that move to subscriptions-api. Each handler, its trigger, what it does, and the RPCs it calls back into subs-api.

Handler	Trigger	What It Does	RPCs to subs-api
FlagAsBadDebt	invoice.marked_uncollectible	Sets bad_debt flag, writes metadata, bans account	FlagAsBadDebt RPC
CheckFlagAsBadDebt	invoice.payment_succeeded	Checks if payment clears bad debt, lifts flag	CheckFlagAsBadDebt RPC
badDebtLift	customer.subscription.updated	Lifts bad debt on subscription reactivation	badDebtLift RPC
CalculateInvoiceBadDebtAmount	Called by FlagAsBadDebt	Prorates invoice to compute bad debt amount	None (local)

APPENDIX B · TEST MATRICES

20 scenarios across three domains. Each scenario must pass in the brain before the corresponding handler is deleted from billing-webhooks.

FlagAsBadDebt scenarios
#	Scenario	Expected
1	Single invoice, PayGo, in-advance only	Flag set, metadata written, ban applied
2	Single invoice, PayGo, mixed in-advance + usage	Flag set, proration on in-advance only
3	Already flagged account	Idempotent — no duplicate flag
4	Enterprise account	Skip — excluded type
5	Partner account	Skip — excluded type
6	Multiple uncollectible invoices	Flag set, amounts summed

Lifting scenarios
#	Scenario	Expected
7	Full payment on single invoice	Flag lifted, ban removed, metadata updated
8	Partial payment (less than bad_debt_amount)	Flag NOT lifted — partial insufficient
9	Payment on consolidated invoice	Flag lifted (legacy path)
10	Payment on credit-note-adjusted original	Flag lifted (new path)
11	Payment on unrelated invoice	Flag NOT lifted — wrong invoice
12	Multi-invoice, pay latest only	Flag lifted (progressive policy)
13	Subscription reactivation without payment	Flag NOT lifted — payment required

Amount calculation scenarios
#	Scenario	Expected
14	$200/mo, uncollectible after 5 days	$200 × (26/31) = $167.74 credit → $32.26 debt
15	Usage-only invoice	$0 credit — usage owed in full
16	Mixed: $20 in-advance + $5.47 usage	Credit on $20 portion only
17	Mid-month uncollectible (day 15 of 30)	$200 × (15/30) = $100 credit → $100 debt
18	Last-day uncollectible (day 30 of 31)	$200 × (1/31) = $6.45 credit → $193.55 debt
19	Multiple line items, different periods	Each prorated independently
20	Zero-amount invoice	No credit note needed

APPENDIX C · DELETION MANIFEST

Each deletion is gated on the corresponding test suite passing in the brain. No deletion without coverage.

What	In	Gated On
FlagAsBadDebt handler	billing-webhooks	Tests 1–6 passing in brain
CheckFlagAsBadDebt handler	billing-webhooks	Tests 7–13 passing in brain
badDebtLift handler	billing-webhooks	Tests 7–13 passing in brain
CalculateInvoiceBadDebtAmount	billing-webhooks	Tests 14–20 passing in brain
FlagAsBadDebt RPC	subscriptions-api	Direct call replaces RPC
CheckFlagAsBadDebt RPC	subscriptions-api	Direct call replaces RPC
badDebtLift RPC	subscriptions-api	Direct call replaces RPC

APPENDIX D · ACCOUNT TYPE CATALOG

Account types determine dunning treatment. The brain must handle every type explicitly — no silent fallthrough to PayGo defaults.

Supported types (full dunning treatment)
Type	Treatment
PayGo	Standard dunning: flag → ban → cancel.
PayGo (Business)	Standard dunning with business account nuances.
Pro	Standard dunning.
Business	Standard dunning.
Enterprise Trial	Standard dunning with trial conversion handling.
Self-Serve Enterprise	Standard dunning.

Excluded types (need explicit rules)
Type	Current Handling
Enterprise (contract)	Excluded from automated dunning. Manual process.
Partner	Excluded. Partner billing handled separately.
Cloudflare Internal	Excluded. Internal accounts.
Free	No billing. Skip.
Channel Partner	Excluded. Third-party billing.

APPENDIX E · CREDIT NOTE INFRASTRUCTURE

The credit note machinery already exists in subscriptions-api. Three issuance paths, an approval pipeline, and a revenue recognition processor. What's missing is one new path — uncollectible invoice adjustment.

Component	What It Does	Status
Registrar refund path	Issues credit notes for registrar-related refunds	Production — existing
Bad debt write-off path	Issues credit notes as part of bad debt write-off	Production — existing
BrainTree webhook path	Issues credit notes from BrainTree payment events	Production — existing
Approval pipeline	6 dollar tiers, daily cron for approvals	Production — existing
credit_note_processor.go	Revenue recognition pipeline, 1060+ lines	Production — existing
Uncollectible adjustment	Credit note at uncollectible time for unused service	NEW — this is the work