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

• 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

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

File / Folder	Purpose
00-context.md	Executive summary, problem statement, and project framing
01-architecture-assessment.md	Current billing flow + Stripe-native target options
02-code-updates.md	Migration/rewrite plan: what code goes away, what thins down, what's new
03-deployment-management.md	How Stripe changes ship (test mode, webhook infra, rollout strategy)
04-runbook.md	Month-end, reconciliation, dispute, and failed-payment procedures in the new world
05-appendix.md	References, inputs, decisions, open questions
Adventive_Stripe_Billing_Transition_Plan.pdf	Final 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

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

• 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.

Quick links

• Final PDF: ./Adventive_Stripe_Billing_Transition_Plan.pdf
• Stripe product docs: https://docs.stripe.com/invoicing · https://docs.stripe.com/billing · https://docs.stripe.com/tax
• Admin sibling: ../Admin Dashboard Cloudflare Migration/