标签：#billing

Why Every Modern SaaS Needs a Billing Engine (Not Just a Payment Gateway) When building a SaaS product, API platform, AI application, or cloud service, most teams start by integrating a payment gateway like Stripe or Paystack. That solves one important problem: Collecting payments. But collecting payments and managing billing are two completely different challenges. As products grow, pricing becomes more sophisticated. Customers expect usage-based billing, flexible subscriptions, prepaid credits, seat-based pricing, tiered plans, and transparent invoices. Suddenly, the billing logic inside the application becomes one of the most complex parts of the entire system. This is why more engineering teams are separating payment processing from billing infrastructure . Payment Processing vs Billing Infrastructure A payment gateway is responsible for moving money. A billing platform is responsible for determining what should be charged, when it should be charged, and why it should be charged. Although these responsibilities often get grouped together, they solve very different problems. Payment providers typically handle: Payment authorization Card processing Refunds Payment retries Bank settlements Customer payment methods A billing engine manages: Usage metering Subscription billing Pricing rules Billing cycles Invoice generation Revenue analytics Customer usage tracking Payment orchestration Multi-gateway billing Proration Credits and quotas Keeping these responsibilities separate makes systems easier to maintain, easier to scale, and much more flexible when pricing changes. Why Billing Logic Doesn't Belong Inside Your Application Many engineering teams start with a simple subscription model. Then the business evolves. Suddenly the product needs to support: API usage billing AI token billing Storage billing Compute billing Per-seat pricing Hybrid subscriptions Enterprise contracts Prepaid credits The application slowly becomes filled with billing-specific code. Developers

TL;DR Moved a SaaS from à-la-carte feature subscriptions (pay per feature) to plans-only (pay for a tier, get its features). Did it in four phases so nothing broke mid-flight: seed plans → gate on plans → migrate orgs → delete the old machinery. Lesson: model migrations are safest as expand → migrate → contract , not a big-bang swap. The problem The old billing let an org subscribe to individual features à la carte. Flexible on paper, painful in practice: entitlement logic had two sources of truth (per-feature subscriptions and an implicit plan), and every gate had to check both. Time to collapse it into one model — you buy a plan , the plan carries the features. The trap with this kind of change is the temptation to rip out the old columns and ship. Do that and every in-flight subscription, every gate check, and every webhook that still speaks the old language breaks at once. The phased plan I ran it as four ordered migrations. Each phase is deployable on its own and leaves the app working. Phase What it does Why this order F1 Seed Plans into the prerequisite chain New model must exist before anything reads it F2 Gate features on the plan, not the feature-sub Reads switch over while writes still dual-run F3 Deploy op migrates existing orgs onto a plan Backfill — nobody left on the old model F4 Remove the à-la-carte machinery Contract — safe only after F3 This is the expand/contract pattern applied to a domain model, not just a schema. Expand (F1) adds the new thing alongside the old. Migrate (F2–F3) moves reads then data. Contract (F4) deletes the old thing once nothing points at it. F1 seed F2 gate on plan F3 backfill orgs F4 drop features ┌────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ plans │ --> │ reads: plan │ -> │ every org on │ -> │ delete a-la- │ │ exist │ │ writes: both │ │ a real plan │ │ carte code │ └────────┘ └──────────────┘ └──────────────┘ └──────────────┘ safe safe safe safe Gating on the plan The gate collapses to a single question

Synchronous billing is easy, and that's the problem — it makes you think all billing is easy. When a request does its work inline, the billable number is in the response by the time you send it. The gateway meters from there — the meter write, retries and all, is its problem, not yours. From your side, synchronous billing is one number in the response. Asynchronous work breaks that. The request submits a job; the work happens later, in a worker; the result comes back through a poll or a callback. And the thing you bill for — characters processed, pages converted — isn't known when the request arrives. It's known when the job finishes . So you can't meter at the edge. The meter has to fire from the completion path. And the real difficulty is firing it exactly once per unit of completed work — because requests, polls, and retries all conspire to make that zero times or many times. This is platform-agnostic. Every submit-process-poll API has it. I'll use the system I run as the example, but the shape is the same anywhere. Three ways metering goes wrong On arrival. Carry the synchronous habit over and you meter when the job is submitted. But you don't know the size yet, so you're forced into a crude flat fee — or you bill for work that hasn't happened and might fail. Wrong unit, wrong time. On retrieval. The subtle one. You wire the meter to fire when the client fetches the result. Now a client who submits a job, lets it run — costing you real money downstream — and never bothers to poll is never billed. You did the work for free. "Completion" is not "the client picked up the result." It's the worker finishing. Without a fixed quantity. Input characters or output characters? Pages before OCR or after? If you haven't decided exactly what you measure and where, invoices drift and customers argue. Decide once; measure there. All three point the same way: meter on measured work-completion, with a fixed definition of the unit. Not on arrival. Not on retrieval. The mechanism:

Move originally planned for Monday would have heavily increased power users' costs.