Skip to content

00 — Context

Problem statement

Adventive operates a custom billing system embedded in the legacy admin application. The current flow is:

  1. Billable items accumulate throughout the month in Adventive's internal system.
  2. At month-end, a rollup job aggregates all billable items per customer.
  3. Adventive calls the Stripe API to create invoices with the rolled-up line items.
  4. Adventive generates a custom-designed invoice PDF (outside of Stripe).
  5. Adventive sends the custom invoice to the customer via Mailgun.
  6. Payment, retries, reconciliation, and dispute handling all route through custom logic.

This means Adventive owns and maintains a meaningful amount of billing infrastructure — rollup logic, invoice rendering, email delivery, reconciliation — that Stripe today offers as a managed product (Invoicing + Hosted Invoice Page + Email Receipts + Tax + Customer Portal). Every component Adventive owns is another surface it must monitor, secure, audit, and evolve.

Business motivation

  • Engineering leverage: billing infrastructure is undifferentiated work. Running it in-house costs developer time that could go to Adventive's actual product.
  • Compliance surface: custom billing carries audit, tax, and record-retention obligations. Stripe carries those for its portion of the stack with better-established controls.
  • Customer experience: Stripe Hosted Invoice Page + Customer Portal provides self-service payment, card updates, and invoice history that Adventive would otherwise have to build.
  • Coupling to legacy admin: billing logic is one of the reasons the legacy admin is hard to unwind. A successful transition simplifies the sibling admin-modernization project.
  • Vendor consolidation opportunity: if billing email moves to Stripe, Mailgun may be retirable (pending audit of other email uses).

Scope

  • In scope — Phase A (viability assessment):
  • Full audit of the current billing pipeline (rollup, invoice gen, send, reconcile, dispute).
  • Feature-by-feature mapping against Stripe Invoicing, Billing, Tax, Customer Portal, and Hosted Invoice Page.
  • Gap analysis — what Stripe does, what it doesn't, what's "close enough," what requires workarounds.
  • Custom invoice design assessment: can Stripe's invoice branding (logo, colors, footer, custom fields) meet Adventive's brand bar, or is the custom renderer non-negotiable?
  • Cost modeling: Stripe fees (if any on invoicing) vs. current run-cost (infra + Mailgun + engineering maintenance).
  • Risk register: tax reporting, audit trail, dispute history, data export.

  • Written go / no-go recommendation per subsystem.

  • In scope — Phase B (migration plan, conditional):

  • Target architecture diagram (Stripe-native vs. hybrid).
  • Data migration plan (customers, products, prices, subscriptions, historical invoices).
  • Webhook / event-handling strategy on Cloudflare Workers.
  • Cutover plan including dual-run and reconciliation period.
  • Rollback strategy at each phase.
  • Mailgun retirement plan if fully displaced.

  • Claude Code handoff package.

  • Out of scope:

  • Payment processing fundamentals (already Stripe — not up for debate).
  • Non-billing uses of Mailgun (separate audit if needed).
  • Product / pricing redesign — this project migrates existing pricing as-is.

  • Admin UI for billing — owned by ../Admin Dashboard Cloudflare Migration/. This project defines what billing ops need to exist; that project defines how they surface.

  • Deferred:

  • Usage-based / metered billing additions (unless trivially enabled by moving to Stripe Billing).
  • Multi-currency expansion.
  • Revenue recognition automation beyond what Stripe provides.

Success criteria

Phase A success:

  1. A documented, evidence-based go / no-go recommendation for each billing subsystem (rollup, invoice gen, invoice delivery, reconciliation, dispute handling).
  2. Cost model showing multi-year TCO for status quo vs. Stripe-native vs. hybrid.
  3. Risk register with severity × likelihood ratings and mitigations.
  4. Sign-off from Jeffrey on which subsystems move in Phase B.

Phase B success (if triggered):

  1. Cutover plan with dual-run period and reconciliation tolerance thresholds.
  2. All customer-visible changes (invoice design, email sender, payment page) reviewed against brand guidelines.
  3. Zero unreconciled invoices during dual-run.
  4. Mailgun / custom renderer / rollup code formally retired from the admin codebase after cutover.

Stakeholders

Role Name Interest
Owner Jeffrey Lambert Architecture, plan quality, go/no-go decision
Approver — Billing Jeffrey + Patrick Joint sign-off on the migration plan
Consulted TBD Accounting — confirm Acodei handling of new Stripe event shape
Informed Customers (~200) End recipients of invoices — any customer-visible change requires comms

Customer population

Approximately 200 invoiced customers, using a mix of pricing models (flat, tiered, usage-based / metered, and custom arrangements). Migration must handle each pricing model cleanly, which drives the choice of Stripe Billing's subscription + metered price constructs. Non-standard billing arrangements (manual invoices, wire-only, deferred terms) exist in the mix and will need individualized migration handling.

Current Stripe footprint

Adventive is already on Stripe Invoices, Billing, and Checkout. This project deepens the use of Billing (subscriptions, tiered pricing, metered prices, retries, dunning) to replace custom calculation and rollup logic — rather than introducing Stripe as a new vendor.

Accounting integration (existing)

Adventive uses the Acodei QuickBooks Sync integration today: Acodei captures Stripe events and pushes to QuickBooks. This stays in place through the migration — Acodei is Stripe-centric by design, so making Stripe the billing source-of-truth actually simplifies the sync path. Adventive is not locked to Acodei and can swap later if needed.

Retention posture

No contractual or regulatory retention constraints beyond tax defaults. Current invoice retention is ~14 years (nothing has ever been deleted). The migration should preserve that history — customer-visible invoice records from the legacy system remain accessible post-cutover.

Tax posture

Adventive does not currently collect or remit tax (volumes below nexus thresholds). Design assumes Stripe Tax is not enabled at cutover but can be enabled later without re-architecture when tax liability triggers.

Project sequencing

This project runs second, after the Admin Dashboard Cloudflare Migration begins. Phase A (viability assessment) can begin in parallel with admin architecture work — it doesn't depend on admin code changes. Phase B (migration plan) should land after the admin API contract stabilizes, because decisions about where billing ops surface in the new admin flow directly from Phase A's conclusions.

Key sequencing constraint: any billing subsystem that moves to Stripe-native reduces scope in the new admin. So the admin project must budget for uncertainty on the billing UI surface area until Phase A of this project concludes.