Skip to content

feat(billing): settle from trusted product principal - #5263

Closed
jeanduplessis wants to merge 2 commits into
transaction-service-fee-2-libraryfrom
transaction-service-fee-3-safety
Closed

feat(billing): settle from trusted product principal#5263
jeanduplessis wants to merge 2 commits into
transaction-service-fee-2-libraryfrom
transaction-service-fee-3-safety

Conversation

@jeanduplessis

@jeanduplessis jeanduplessis commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Summary

Makes existing settlement paths derive credits, entitlements, affiliate value, and emails from trusted product principal rather than gross Stripe payment amounts.

Why this change is needed

Once a service fee is added, gross paid is no longer equal to the product purchased. Charging first would risk over-crediting users, inflating Kilo Pass value, and paying affiliate commission on Kilo's fee. This safety slice changes those assumptions before any fee path is activated.

How this is addressed

  • Classify Stripe invoice lines so fee lines cannot be mistaken for credits, Kilo Pass, seats, or other product value.
  • Settle personal and organization credits from product principal rather than charge or invoice gross.
  • Keep affiliate and PostHog product amounts fee-exclusive.
  • Make top-up email inputs explicit about product, fee, credits, and total paid.
  • Preserve existing fee-free behavior; this PR still does not attach a fee.

Stack: #5236#5262#5263 (this PR) → #5264#5265#5266.

Human Verification

No new product or browser verification was performed while publishing this PR. Focused regression tests in the diff cover legacy settlement, line classification, affiliate amounts, and email contracts.

Reviewer Notes

Human Reviewer Flags

  • This ordering is intentional: correct the gross-versus-principal invariant before introducing a second invoice line.
  • Product value comes from trusted classified lines and metadata, never by subtracting an assumed 5% from gross.
  • Existing pre-activation and fee-free Stripe events remain supported.

Code Reviewer Agent

Code Reviewer Notes
  • Pay close attention to legacy webhook compatibility and fallback behavior.
  • Affiliate rule 17 is updated so commission excludes service-fee revenue.
  • Top-up emails itemize a positive fee but omit the row for fee-free purchases.

Comment thread apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.ts
Comment thread apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.ts
Comment thread apps/web/src/lib/stripe/index.test.ts
@kilo-code-bot

kilo-code-bot Bot commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Code Review Summary

Status: 3 Issues Found | Recommendation: Address before merge

Executive Summary

The new unconditional Kilo Pass invoice settlement call will spam admin Slack with a "missed service fee" alert for every legacy invoice until the 2026-09-01 fee activation, and the PR also removes ~370 lines of still-relevant webhook dispatch tests.

Overview

Severity Count
CRITICAL 0
WARNING 2
SUGGESTION 1
Issue Details (click to expand)

WARNING

File Line Issue
apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.ts 535 Missing-assessment Slack alert is not activation-gated; fires for every legacy Kilo Pass invoice.paid until 2026-09-01
apps/web/src/lib/stripe/index.test.ts 3622 ~370 lines of processStripePaymentEventHook dispatch tests deleted without relocation while the dispatch logic still exists

SUGGESTION

File Line Issue
apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.ts 543 Bare catch {} swallows settlement failures with no logging, silently zeroing analytics/affiliate amounts
Files Reviewed (23 files)
  • .plans/service-fees/SPEC.md
  • .plans/service-fees/VALIDATION.md
  • .specs/impact-affiliate-tracking.md
  • apps/web/src/emails/AGENTS.md
  • apps/web/src/emails/creditsTopUp.html
  • apps/web/src/lib/autoTopUp.ts
  • apps/web/src/lib/credits.test.ts
  • apps/web/src/lib/credits.ts
  • apps/web/src/lib/email.ts
  • apps/web/src/lib/kilo-pass/affiliate-sale.test.ts
  • apps/web/src/lib/kilo-pass/affiliate-sale.ts
  • apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.test.ts
  • apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.ts - 2 issues
  • apps/web/src/lib/kilo-pass/stripe-invoice-classifier.server.test.ts
  • apps/web/src/lib/kilo-pass/stripe-invoice-classifier.server.ts
  • apps/web/src/lib/kiloclaw/stripe-invoice-classifier.server.test.ts
  • apps/web/src/lib/organizations/organization-billing.test.ts
  • apps/web/src/lib/organizations/organization-billing.ts
  • apps/web/src/lib/purchase-emails.test.ts
  • apps/web/src/lib/stripe/index.test.ts - 1 issue
  • apps/web/src/lib/stripe/index.ts
  • apps/web/src/routers/admin/email-testing-router.ts
  • docs/adr/0004-stripe-service-fee-assessment.md

Fix these issues in Kilo Cloud

Previous Review Summaries (2 snapshots, latest commit bd77e1d)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit bd77e1d)

Status: 3 Issues Found | Recommendation: Address before merge

Executive Summary

The new unconditional Kilo Pass invoice settlement call will spam admin Slack with a "missed service fee" alert for every legacy invoice until the 2026-09-01 fee activation, and the PR also removes ~370 lines of still-relevant webhook dispatch tests.

Overview

Severity Count
CRITICAL 0
WARNING 2
SUGGESTION 1
Issue Details (click to expand)

WARNING

File Line Issue
apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.ts 535 Missing-assessment Slack alert is not activation-gated; fires for every legacy Kilo Pass invoice.paid until 2026-09-01
apps/web/src/lib/stripe/index.test.ts 3622 ~370 lines of processStripePaymentEventHook dispatch tests deleted without relocation while the dispatch logic still exists

SUGGESTION

File Line Issue
apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.ts 543 Bare catch {} swallows settlement failures with no logging, silently zeroing analytics/affiliate amounts
Files Reviewed (20 files)
  • .specs/impact-affiliate-tracking.md
  • apps/web/src/emails/AGENTS.md
  • apps/web/src/emails/creditsTopUp.html
  • apps/web/src/lib/autoTopUp.ts
  • apps/web/src/lib/credits.test.ts
  • apps/web/src/lib/credits.ts
  • apps/web/src/lib/email.ts
  • apps/web/src/lib/kilo-pass/affiliate-sale.test.ts
  • apps/web/src/lib/kilo-pass/affiliate-sale.ts
  • apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.test.ts
  • apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.ts - 2 issues
  • apps/web/src/lib/kilo-pass/stripe-invoice-classifier.server.test.ts
  • apps/web/src/lib/kilo-pass/stripe-invoice-classifier.server.ts
  • apps/web/src/lib/kiloclaw/stripe-invoice-classifier.server.test.ts
  • apps/web/src/lib/organizations/organization-billing.test.ts
  • apps/web/src/lib/organizations/organization-billing.ts
  • apps/web/src/lib/purchase-emails.test.ts
  • apps/web/src/lib/stripe/index.test.ts - 1 issue
  • apps/web/src/lib/stripe/index.ts
  • apps/web/src/routers/admin/email-testing-router.ts

Fix these issues in Kilo Cloud

Previous review (commit 6f363aa)

Status: 3 Issues Found | Recommendation: Address before merge

Executive Summary

The new unconditional Kilo Pass invoice settlement call will spam admin Slack with a "missed service fee" alert for every legacy invoice until the 2026-09-01 fee activation, and the PR also removes ~370 lines of still-relevant webhook dispatch tests.

Overview

Severity Count
CRITICAL 0
WARNING 2
SUGGESTION 1
Issue Details (click to expand)

WARNING

File Line Issue
apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.ts 535 Missing-assessment Slack alert is not activation-gated; fires for every legacy Kilo Pass invoice.paid until 2026-09-01
apps/web/src/lib/stripe/index.test.ts 3622 ~370 lines of processStripePaymentEventHook dispatch tests deleted without relocation while the dispatch logic still exists

SUGGESTION

File Line Issue
apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.ts 543 Bare catch {} swallows settlement failures with no logging, silently zeroing analytics/affiliate amounts
Files Reviewed (20 files)
  • .specs/impact-affiliate-tracking.md
  • apps/web/src/emails/AGENTS.md
  • apps/web/src/emails/creditsTopUp.html
  • apps/web/src/lib/autoTopUp.ts
  • apps/web/src/lib/credits.test.ts
  • apps/web/src/lib/credits.ts
  • apps/web/src/lib/email.ts
  • apps/web/src/lib/kilo-pass/affiliate-sale.test.ts
  • apps/web/src/lib/kilo-pass/affiliate-sale.ts
  • apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.test.ts
  • apps/web/src/lib/kilo-pass/stripe-handlers-invoice-paid.ts - 2 issues
  • apps/web/src/lib/kilo-pass/stripe-invoice-classifier.server.test.ts
  • apps/web/src/lib/kilo-pass/stripe-invoice-classifier.server.ts
  • apps/web/src/lib/kiloclaw/stripe-invoice-classifier.server.test.ts
  • apps/web/src/lib/organizations/organization-billing.test.ts
  • apps/web/src/lib/organizations/organization-billing.ts
  • apps/web/src/lib/purchase-emails.test.ts
  • apps/web/src/lib/stripe/index.test.ts - 1 issue
  • apps/web/src/lib/stripe/index.ts
  • apps/web/src/routers/admin/email-testing-router.ts

Fix these issues in Kilo Cloud


Reviewed by grok-4.6 · Input: 65.2K · Output: 9.7K · Cached: 125.4K

Review guidance: REVIEW.md from base branch transaction-service-fee-2-library

@jeanduplessis
jeanduplessis force-pushed the transaction-service-fee-2-library branch from 842d6ec to ce00251 Compare August 18, 2026 16:33
@jeanduplessis
jeanduplessis force-pushed the transaction-service-fee-3-safety branch 2 times, most recently from bd77e1d to c83e1e2 Compare August 18, 2026 19:08
@jeanduplessis
jeanduplessis force-pushed the transaction-service-fee-2-library branch from ce00251 to 1e58993 Compare August 18, 2026 19:08
Stop treating Stripe gross paid amounts as product value. Settlement
now reads a trusted principal, classifiers ignore fee lines, and
Impact Kilo Pass sales use the product amount. No fee is charged yet.
@jeanduplessis

Copy link
Copy Markdown
Contributor Author

Superseded by #5383, which consolidates the complete service-fee implementation into one PR against main.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant