At $5M ARR, manual billing breaks. This technical guide covers billing infrastructure API architecture, build vs. buy decisions, and vendor evaluation for B2B SaaS.
Evelyn Ly
Head of Marketing
At $5M ARR, your Stripe-plus-spreadsheet billing setup hits a wall.
Not a metaphorical one. A real one where your finance team spends 40+ hours a month reconciling invoices, your engineering team burns sprints fixing billing edge cases, and you're leaking 2-5% of revenue through failed charges and manual errors nobody catches until month-end close.
The fix isn't "better spreadsheets." It's infrastructure. Specifically, a billing infrastructure API that connects your contracts, usage data, invoicing, and payments into one programmable system.
This guide covers what billing infrastructure APIs actually are, how they work at the architecture level, when to build versus buy, and how to evaluate vendor APIs without getting sold a bill of goods. Whether you're a VP of Finance trying to understand what your engineering team is proposing, or an engineer evaluating whether to build or buy, this is for you.
A billing infrastructure API is the programmable layer that handles how your SaaS company meters usage, calculates prices, generates invoices, and collects payments. Instead of managing these functions through manual processes or disconnected UIs, an API lets your systems talk to each other automatically.
Think of it as the nervous system connecting your contracts to your revenue. When a customer signs a deal, the API knows what to bill, when to bill it, and how to recognize that revenue. No human copying numbers between tabs.
Four pillars make up a modern billing infrastructure API:
Metering and usage tracking. The data collection layer that records what customers actually consume. API calls, seats, compute hours, tokens, whatever your pricing model measures.
Pricing engine. The logic that applies your pricing rules to raw usage data. Tiered pricing, volume discounts, custom negotiated rates, ramp schedules. All calculated programmatically.
Invoicing. The generation, preview, and delivery of invoices based on what the pricing engine produces. Includes adjustments, credits, and custom line items.
Payment processing. The actual collection of money. Charge attempts, dunning workflows, payment method management, and reconciliation.
A billing platform with a nice dashboard but no API is a dead end for any SaaS company past early stage. Here's why.
Manual processes don't survive pricing changes. When you introduce usage-based pricing or custom contract terms, you need programmatic control. You can't click through a UI to adjust 200 customer subscriptions.
Integrations require APIs. Your CRM, accounting system, data warehouse, and commission tools all need billing data. Without an API, someone is exporting CSVs and uploading them manually. That's where errors hide.
Real-time capabilities demand automation. Usage threshold alerts, mid-cycle upgrades, prorated charges. These events happen constantly. An API handles them in milliseconds. A human handles them next Tuesday.
Not every company needs this immediately. A startup with 20 customers on simple monthly subscriptions can get by with Stripe Checkout and a spreadsheet. But you've outgrown that approach when:
Companies at $3-10M ARR with 200+ customers typically cross this threshold. The exact moment varies, but the signal is consistent: manual billing becomes a constraint on growth.
This is where most guides stay surface-level. Let's go deeper.
Usage and metering APIs form the foundation. They accept events that represent customer activity.
curl -X POST https://api.billing.com/v1/events \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"event_id": "evt_abc123",
"customer_id": "cust_456",
"event_name": "api_call",
"timestamp": "2025-01-15T10:30:00Z",
"properties": {
"tokens_used": 1500,
"model": "gpt-4",
"region": "us-east-1"
}
}'
Notice the event_id field. That's an idempotency key. If your system retries this request (network timeout, server error), the billing API recognizes the duplicate and doesn't double-count. This matters enormously. Without idempotency, usage-based billing becomes unreliable.
Pricing APIs let you define and apply pricing rules programmatically. You create price objects that attach to plans, and the API applies them to usage data:
{
"price_id": "price_789",
"type": "tiered",
"tiers": [
{"up_to": 1000, "unit_amount": 0.10},
{"up_to": 10000, "unit_amount": 0.08},
{"up_to": null, "unit_amount": 0.05}
],
"billing_period": "monthly"
}
Invoicing APIs generate, preview, and finalize invoices. The preview endpoint is critical. It lets you show customers what their bill will look like before it's finalized:
GET /v1/invoices/preview?customer_id=cust_456&as_of=2025-01-31
Customer and subscription APIs manage lifecycle events. Creating subscriptions, handling upgrades and downgrades, managing seats, and processing cancellations. All through code, not clicks.
The best billing infrastructure APIs follow an event-driven architecture. Here's how the data flows:
Your application emits usage events. These events hit a metering API that validates, deduplicates, and stores them. A processing layer aggregates usage by customer and billing period. The pricing engine applies contract-specific rates. The invoicing system generates bills on schedule.
Webhooks push notifications back to your systems. When an invoice finalizes, when a payment fails, when a customer hits a usage threshold. Your application subscribes to these events:
// Webhook handler for failed payments
app.post('/webhooks/billing', (req, res) => {
const event = req.body;
if (event.type === 'payment.failed') {
const { customer_id, invoice_id, failure_reason } = event.data;
// Notify customer success team
notifySlack(`Payment failed for ${customer_id}: ${failure_reason}`);
// Trigger dunning workflow
startDunningSequence(customer_id, invoice_id);
// Update CRM record
updateSalesforceAccount(customer_id, { payment_status: 'delinquent' });
}
res.status(200).send('OK');
});
This webhook pattern keeps your billing, CRM, and internal tools in sync without polling. When something happens in billing, every connected system updates automatically.
Billing APIs need clear relationships between entities. A customer has subscriptions. Each subscription references a plan with pricing. Usage events attach to customers and specific meters. Invoices aggregate everything for a billing period.
The critical design choice: the contract as source of truth. When a customer signs a deal with custom terms, tiered pricing, and a ramp schedule, that contract should drive everything downstream. If billing, revenue recognition, and commission data derive from separate sources, discrepancies accumulate. Most scaling companies discover this during month-end close when numbers don't reconcile across systems.
This is the question every scaling SaaS company faces. And the honest answer isn't one-size-fits-all.
Building makes sense in specific scenarios:
Extremely unique pricing logic. If your pricing model involves multi-dimensional calculations that no vendor supports natively. Think AI compute costs that factor in model type, token count, latency tier, and time-of-day pricing simultaneously.
Regulatory requirements. Data residency mandates, industry-specific compliance requirements, or government contracts that prohibit third-party data processing.
Already deep in custom infrastructure. If you have a team maintaining billing systems and the cost of migration exceeds the cost of continuing to build.
But be honest about the true costs. A custom billing system isn't a 6-month project. It's a 6-month build followed by permanent maintenance. Revenue recognition alone adds months of complexity. PCI compliance adds more. Audit trail requirements add more still.
Realistic numbers: $500K-$2M to build, plus $200K-400K annually in engineering maintenance. And that's before counting the opportunity cost of engineers not building your core product.
Buying works when your pricing model, while complex, fits within patterns that vendors already support. That includes:
The hidden costs of buying aren't the sticker price. They're vendor lock-in (what happens when you outgrow them), customization ceilings (the workarounds you'll build for missing features), and per-transaction fees that compound as you scale.
Evaluating billing systems requires looking beyond the demo. Ask about data ownership. Ask about API rate limits at your projected scale. Ask what happens when you need to migrate.
Increasingly, the smart play is hybrid. Use vendor APIs for commodity functions (payment processing, invoice delivery, tax calculation) and build custom logic for your differentiators (unique metering, proprietary pricing algorithms, custom workflows).
The key to hybrid: architect for vendor independence. Abstract your billing vendor behind an internal API layer. If you need to swap providers later, you change the adapter, not every system that touches billing.
Here's a practical decision matrix:
.png)
For most B2B SaaS companies between $3-10M ARR, buying or hybrid wins. Building takes too long and distracts engineering from what actually differentiates your product.
When you're evaluating billing infrastructure APIs, here's what actually matters. Not the marketing page. The API documentation.
The metering API needs to handle volume without breaking. At $10M ARR with usage-based pricing, you might process millions of events daily. Key requirements:
Event deduplication. Idempotency keys that prevent double-counting when retries happen. This is non-negotiable.
Batching support. Sending events one-by-one works at small scale. At volume, you need batch endpoints that accept thousands of events per request.
Historical queries. Your finance team needs to pull usage data for specific periods. Your customer success team needs to show customers their consumption trends. The API should support flexible time-range queries.
Multi-dimensional metering. Simple per-unit counting isn't enough for modern SaaS. You need to meter across multiple dimensions. Tokens used by model type by customer tier, for example.
Your pricing will change. Guaranteed. The API needs to support complex pricing without requiring engineering sprints for every change.
Test for these capabilities: Can you create custom pricing for a single customer via API? Can you implement ramp pricing where rates change over the contract term? Can you grandfather existing customers on old pricing while new customers get updated rates? Can you apply mid-cycle pricing changes prorated correctly?
If the answer to any of these requires a support ticket to the vendor, that's a warning sign.
A billing API that doesn't connect to your existing stack creates more manual work, not less.
CRM sync. Bi-directional data flow with Salesforce or HubSpot. When a deal closes, billing activates. When a customer churns, CRM updates.
Accounting systems. Revenue data needs to flow into your general ledger with correct account mapping. This is where month-end close either takes 2 days or 2 weeks.
Data warehouse. Analytics teams need billing data in Snowflake or BigQuery for revenue analysis, cohort studies, and forecasting.
Commission systems. When billing data is separate from commission tracking, reps get paid late and finance reconciles manually. Look for APIs that either handle commissions natively or provide clean webhooks that feed dedicated commission tools like CaptivateIQ or QuotaPath.
ASC 606 and IFRS 15 compliance isn't optional for SaaS companies seeking investment or acquisition. Your billing API needs to support:
APIs must provide complete, immutable records of every financial transaction. SOC 2 auditors will ask for them. If your billing system can't produce them programmatically, you're back to spreadsheets during audit season.
Getting the API working is step one. Making it reliable is what matters.
Billing APIs handle financial data. Security isn't an afterthought.
Rotate API keys on a schedule. Never embed them in client-side code. Use webhook signatures to verify that incoming payloads actually come from your billing provider. Encrypt all data in transit (TLS 1.3 minimum) and at rest.
Rate limiting protects both you and your vendor. Understand your vendor's limits. Design your integration to stay within them. Queue events during traffic spikes rather than dropping them.
Financial systems can't lose data. Every state-changing operation needs idempotency, and every failed request needs intelligent retry logic:
import time
import requests
def post_usage_event(event, max_retries=5):
for attempt in range(max_retries):
try:
response = requests.post(
'https://api.billing.com/v1/events',
json=event,
headers={'Idempotency-Key': event['event_id']},
timeout=10
)
if response.status_code == 200:
return response.json()
elif response.status_code == 429:
# Rate limited - back off
wait = 2 ** attempt
time.sleep(wait)
elif response.status_code >= 500:
# Server error - retry with backoff
wait = 2 ** attempt
time.sleep(wait)
else:
# Client error - don't retry
raise BillingError(response.json())
except requests.Timeout:
if attempt == max_retries - 1:
# Queue for later processing
queue_failed_event(event)
raise
time.sleep(2 ** attempt)
The idempotency key ensures that retried requests don't create duplicate charges. The exponential backoff prevents overwhelming a recovering service. The fallback queue ensures no events are lost permanently.
Never test billing in production. That sounds obvious, but many teams skip proper test environments because billing is "just payments."
Use your vendor's test mode with realistic data volumes. Don't just test the happy path. Test failed payments, partial refunds, mid-cycle upgrades, usage spikes, and what happens when your metering service goes down for 30 minutes.
Preview endpoints (like invoice previews) let you validate calculations before finalizing. Use them in staging to verify that pricing logic produces correct results across edge cases.
Track these metrics from day one:
Set alerts for anomalies. A sudden drop in usage events might mean your metering integration broke, not that customers stopped using your product.
Let's be direct about what's out there and what each category does well.
Stripe Billing is the default starting point. The developer experience is genuinely excellent. Documentation is clear, SDKs exist for every language, and you can get basic subscription billing running in an afternoon.
But Stripe has limits. Custom B2B contracts with negotiated pricing, multi-year ramp schedules, and complex revenue recognition aren't its strength. As your pricing model grows beyond simple per-seat or per-unit, you start building workarounds.
Chargebee, Recurly, Zuora, and Maxio offer deeper billing features than payment processors. They handle subscription lifecycle management, dunning, and basic revenue recognition.
The trade-off: older platforms carry architectural debt. APIs that were designed in 2012 feel different from APIs designed in 2020. Complexity creeps in as you layer on features that were bolted on rather than designed together.
Orb, Lago (open-source), and similar tools give engineering teams maximum control. They're API-native, transparent, and configurable.
The trade-off: operational burden. Open-source means you own hosting, scaling, security patching, and compliance. That's engineering time not spent on your product.
A newer category treats billing, revenue recognition, and commissions as one connected system rather than separate tools you integrate yourself. The contract becomes the source of truth, and downstream functions (invoicing, rev rec schedules, commission calculations) derive from it automatically.
The appeal is less reconciliation. When billing and rev rec share the same data model, month-end close gets simpler. When commissions calculate from the same contract data finance uses, disputes drop.
The trade-off: these platforms are younger and typically smaller than established billing-first vendors. Evaluate maturity, customer references at your scale, and what happens if you outgrow them. But for companies tired of maintaining integrations between three or four tools that were never designed to work together, this category is worth evaluating.
Billing migration is painful. But staying on broken infrastructure is more painful. Here's how to make it work.
Start by documenting what's actually happening today. Every spreadsheet, every manual step, every workaround. You can't automate what you don't understand.
Clean your data before migration. Duplicate customer records, inconsistent pricing, and orphaned subscriptions will all follow you to the new system if you don't fix them first.
Run parallel systems during transition. Generate invoices in both old and new systems for at least one billing cycle. Compare outputs. When they match, cut over.
The biggest risk isn't technical. It's customer disruption. Payment methods need to migrate cleanly. Invoice formatting changes confuse AP departments. Billing dates shifting creates cash flow surprises.
Plan for a 3-6 month transition window. Migrate new customers first. Then move existing customers in cohorts, starting with the simplest accounts. Save enterprise customers with custom contracts for last.
You don't have to migrate everything at once. Start with one function. Maybe metering, because your current approach is the most broken. Get that working, then add pricing automation, then invoicing.
Each phase delivers value independently. And if something goes wrong, you haven't disrupted your entire revenue operation.
The trajectory is clear: more automation, more intelligence, less manual intervention.
AI-powered capabilities are already emerging. Anomaly detection that flags unusual usage patterns before they become billing disputes. Predictive models that identify churn risk from consumption trends. Dynamic dunning optimization that adjusts retry timing based on payment history.
Real-time processing is replacing batch. Instead of generating invoices at month-end from aggregated data, modern APIs produce live invoice previews that update with every usage event. Customers see exactly what they'll owe. Finance sees revenue forming in real-time.
Embedded finance is expanding what billing APIs can do. Split payments for marketplace models, B2B buy-now-pay-later options, and financing built into the billing flow.
Start this week. Document your current billing pain points. Calculate how many hours your team spends on manual billing tasks monthly. Map every system that touches revenue data.
Then bring engineering into the conversation. Not to build something, but to evaluate what's available. The best billing infrastructure decisions happen when finance and engineering align on requirements before anyone writes code or signs a vendor contract.
Document your current architecture. How do usage events flow? Where does pricing logic live? What integrations exist between billing and other systems? What breaks most often?
Then evaluate honestly: is maintaining this infrastructure the best use of your team's time? If your engineers spend 20% of their sprints on billing maintenance, that's a signal.
Your billing infrastructure is revenue infrastructure. Every failed charge, every manual reconciliation, every pricing change that requires an engineering sprint is a direct drag on growth.
The right billing infrastructure API connects your contracts to your billing to your revenue recognition to your commissions. One system. One source of truth. Updates propagate automatically.
Not every company needs to build. Not every company should buy the first vendor they demo. But every company past $3M ARR needs to make this decision deliberately rather than letting infrastructure debt accumulate until month-end close becomes a fire drill.
Start with your pain points. Calculate the real cost of manual processes. Bring finance and engineering into the same room before evaluating vendors. The companies that get billing infrastructure right aren't the ones with the biggest budget. They're the ones that made the decision intentionally instead of letting it happen to them.
Billing and revenue automation that handles contracts, invoicing, revenue recognition, and commissions in one connected system. Book a demo to see how Measure works.
