Skip to content
Adventive Adventive Engineering

Stripe Billing Transition

Assess the viability of retiring Adventive’s custom billing system (month-end rollup, invoice generation, Mailgun delivery) in favor of Stripe-native functionality — and, where viable, produce the migration plan to execute the transition.

Status

Section titled “Status”
  • Owner: Jeffrey Lambert
  • Status: Planning — viability assessment phase
  • Started: 2026-04-23
  • Target: TBD (define after viability assessment)
  • Repository: Shares code with ~/Repositories/BitBucket/adventive-admin today; target state is Stripe-hosted with thin Adventive-side glue.

What this project delivers

Section titled “What this project delivers”

A two-phase engineering plan in the standard Adventive Engineering format:

Phase A — Viability Assessment:

  • Current billing flow audit (rollup, line items, invoice generation, email, reconciliation).
  • Feature-by-feature mapping to Stripe products: Invoicing, Billing, Tax, Checkout, Hosted Invoice Page, Email Receipts.
  • Gap analysis: what Stripe covers natively, what needs custom glue, what can’t move at all.
  • Cost model: Stripe fees on invoicing/tax vs. current hosting + Mailgun + dev-maintenance cost.
  • Risk register: customer experience, compliance (tax/SOX/audit trail), brand (invoice design), data-sovereignty.
  • Go / no-go recommendation with rationale.

Phase B — Migration Plan (conditional on Phase A green-light):

  • Target architecture (Stripe-native vs. hybrid).
  • Data migration plan: customers, prices, subscriptions, historical invoices.
  • Cutover plan with dual-run / reconciliation period.
  • Rollback strategy.
  • Mailgun retirement path (if billing was the primary use).
  • Claude Code handoff package.

What’s in this folder

Section titled “What’s in this folder”
File / FolderPurpose
00-context.mdExecutive summary, problem statement, and project framing
01-architecture-assessment.mdCurrent billing flow + Stripe-native target options
02-code-updates.mdMigration/rewrite plan: what code goes away, what thins down, what’s new
03-deployment-management.mdHow Stripe changes ship (test mode, webhook infra, rollout strategy)
04-runbook.mdMonth-end, reconciliation, dispute, and failed-payment procedures in the new world
05-appendix.mdReferences, inputs, decisions, open questions
Adventive_Stripe_Billing_Transition_Plan.pdfFinal deliverable (WeasyPrint, house style)
code/Reference implementations: webhook handlers, rollup job, reconciliation scripts
inputs/Current invoice samples, Stripe API references, Mailgun usage stats, billing SQL exports
decisions/ADR files: YYYY-MM-DD-title.md

Serverless viability summary

Section titled “Serverless viability summary”

The residual Adventive-side billing logic after moving to Stripe Billing is a strong fit for Cloudflare Workers. The billing Worker has four functions: webhook ingestion (invoice.finalized → PDF render → Mailgun send), metered usage ingestion (POST /usage → Stripe Usage Records), daily reconciliation (Cron Trigger comparing Stripe totals to Acodei/QuickBooks), and an operator admin endpoint for invoice resend. All four are stateless request handlers or short-lived cron jobs that fit comfortably within Workers CPU and memory limits. The one component with a resource consideration is PDF rendering: Cloudflare Browser Rendering allows 2 simultaneous renders per account, which is sufficient at ~200 invoices/month at non-simultaneous pacing. If invoice volume scales to concurrent batch finalization, a Workers Queue can serialize render requests without architectural change. The entire Adventive-side billing glue is estimated to run at under $3/month incremental cost (Workers + Browser Rendering + R2) on the existing Paid plan — while eliminating the EC2 instance running billing_service, a larger recurring cost. The legacy billing_service internal API (separate from the admin repo) is the primary retirement target; it houses the rollup job, Stripe API calls, and PDF renderer that the billing Worker replaces.

Dependencies and adjacencies

Section titled “Dependencies and adjacencies”
  • Sibling project: ../Admin Dashboard Cloudflare Migration/ — runs first. The new admin’s API surface defines where billing ops live in the UI, so Phase B migration-plan work should follow admin API stabilization.
  • Upstream pattern: ../Public API Cloudflare Migration/ — webhook handlers, Cron Triggers, Queues all follow that project’s deployment conventions.
  • Adjacent vendor: Stripe — configured via the Stripe MCP connector for live API exploration during the viability assessment.
Section titled “Quick links”