标签：#billing

This is a story of how you receive a higher bill than expected and how GitHub's Billing Controls help clarity and predictability. Let's begin our story. Confusion: The bill is higher than expected The AI bill is higher than expected. Now what? Finance wants to understand what is driving the cost. Engineering leaders, on the other hand, want to preserve the productivity gains behind the increased usage. The administrator needs to balance both priorities and put a policy in place that the business can understand. One question drives the investigation: Where is the increase coming from, and how do we control it without disrupting valuable work? To answer it, we first need to follow the spend. Once we know who owns it, we can apply guardrails at the right level. Investigation: Follow the spend Setting a limit too early could restrict useful adoption without addressing the main source of cost. So, let's find out what changed and who can act on it. The investigation begins in the billing administration portal, where usage and budget settings appear in one place. Fig 01: A unified billing workspace connects usage evidence to budget controls. Identify the consumption category First, we identify which product changed. GitHub reports this by SKU , which simply means the billing category for a product or service. Fig 02: Grouping metered usage by billing category highlights Copilot Enterprise usage. Grouping usage by billing category shows which product is driving the increase. In this example, the chart points to Copilot Enterprise usage. Leaders can then ask whether that growth comes from valuable adoption, an unusual workload, or demand that has outgrown its budget. Locate the accountable organization Once you know which product is driving the cost, find out who owns the usage. An enterprise-wide total can hide a sharp increase in one organization. Fig 03: Organization-level grouping identifies the business unit accountable for demand. The organization view points to the le

The pricing formulas in Motor, the estimating engine I built for a water feature shop, did not come from the manual. I pulled 32 of them out of the JavaScript behind Aquascape's contractor calculator, the tool contractors actually use to bid jobs. The manual was sitting right there, official and free. Ignoring it was the best design decision in the whole system. A vendor never ships a sloppy calculator Why trust the calculator over the manual? Because of what happens when each one is wrong. If the manual sizes a pump wrong, a reader shrugs and moves on. If the calculator sizes a pump wrong, a contractor bids a job at that number, wins it, and loses money on the install. Then the phone rings. So calculators get fixed and manuals drift. Give it ten years and the two quietly disagree, and everyone in the trade knows which one to trust without anyone saying so. A vendor will ship a sloppy PDF. They will never ship a sloppy calculator. Documentation is what a domain says about itself. The artifacts money flows through are what it actually believes. Once you see that split, you cannot stop seeing it. The other half was in old invoices Formulas only get you to cost. What a shop charges on top of cost is a belief about its market, and no vendor document holds that number. So I pulled 132 historical quotes out of the shop's CRM. Real quotes, sent to real customers, most of them paid. I calibrated Motor's markup against those, then checked its output against what the shop had actually charged. The result: Calibrated against 132 real quotes, Motor's estimates landed within 5 percent of what the shop actually charged, with no pricing rule taken from documentation. I could have just asked the owner what his markup was. But what an owner says and what his invoices show are rarely the same number, and the invoices are the ones customers paid. When the two disagree, believe the invoices. The same bug in a different industry I build and run systems in several industries, and the sur

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.