Prompt
How do I build a billing layer for a hybrid pricing model?
Latest observation
To build a billing layer for a hybrid pricing model, design it around a clear separation between:
- Pricing rules — what should be charged
- Usage collection — what actually happened
- Metering and aggregation — how usage becomes billable quantities
- Rating — how quantities turn into money
- Invoicing and payments — how charges are presented and collected
A hybrid model usually combines some mix of:
- Subscription fee (recurring base charge)
- Usage-based pricing (per API call, GB, seat, compute, etc.)
- Tiered pricing (price changes after thresholds)
- Overages (extra usage after included amount)
- Feature/add-on charges (premium modules, compliance, support)
- Commitments/credits (prepaid spend, minimums, discounts)
1. Start with a pricing contract model
Define a product catalog that can express all price components.
Example objects:
- Plan
- Price component
- Meter
- Tier
- Included allowance
- Discount
- Commitment
- Billing period
- Customer contract / subscription
A plan might look like:
- $100/month base fee
- Includes 10,000 API calls
- $0.01 per additional API call
- $0.002 per GB processed
- 10% discount on annual commitments
This should be data-driven, not hardcoded.
2. Separate usage events from billable usage
Your system should collect raw usage events first, then transform them into billable units.
Raw event example
{
"customer_id": "cus_123",
"meter": "api_call",
"quantity": 1,
"timestamp": "2026-11-16T12:34:56Z",
"metadata": {
"endpoint": "/v1/search",
"region": "us-east-1"
}
}
Billable aggregation example
- API calls this month: 12,340
- Included: 10,000
- Overage: 2,340
- Charge: 2,340 × $0.01 = $23.40
For hybrid pricing, the same customer may also have:
- a base subscription charge
- seat charges
- usage overage charges
- a support add-on
3. Build a rating engine
The rating engine converts usage into charges.
It should support:
- Flat recurring fees
- Per-unit charges
- Tiered rates
- Graduated tiers
- Volume tiers
- Included usage
- Minimum monthly spend
- Proration
- Discounts/promotions
- Regional or product-specific pricing
- Tax calculation hooks
Rating pipeline
- Fetch customer contract
- Aggregate usage by meter and billing period
- Apply included allowances
- Determine tier band
- Compute charge
- Apply discounts/credits
- Add taxes/fees
- Produce line items
Keep each step deterministic and auditable.
4. Use line items as the source of truth for invoices
Invoices should be composed of line items, each traceable back to pricing and usage.
Example invoice line items:
- Base subscription: $100.00
- API calls overage: $23.40
- Storage usage: $8.20
- Support add-on: $50.00
- Discount: -$10.00
- Tax: $13.16
Each line item should include:
- description
- amount
- quantity
- unit price
- meter reference
- billing period
- source usage summary
- pricing rule version
This makes audits and customer disputes much easier.
5. Version your pricing rules
Hybrid pricing changes over time. Never overwrite pricing in place without versioning.
Store:
- effective start/end dates
- plan version
- pricing rule version
- currency
- region
- grandfathering logic for existing customers
This allows:
- old customers to stay on old rates
- new customers to get new pricing
- retroactive invoice reproducibility
6. Make usage processing idempotent
Billing systems must handle retries and duplicate events safely.
Use:
- unique event IDs
- deduplication windows
- idempotency keys
- immutable raw usage records
If the same usage event is ingested twice, it should only count once.
7. Support asynchronous billing workflows
Usage billing is usually not real-time invoice generation. Use a pipeline like:
- ingest usage events
- validate and store raw events
- aggregate usage periodically
- rate usage at period close
- generate invoice draft
- apply approvals/disputes
- finalize invoice
- charge payment method
- reconcile payment status
This is often implemented with queues or jobs rather than synchronous requests.
8. Model credits, minimums, and commitments carefully
Hybrid models often include contract terms that complicate billing.
Common cases
- Prepaid credits: deduct usage from balance before charging cash
- Minimum spend: if usage is low, bill up to a floor
- Committed spend: customer pays $X/month regardless of usage
- Rollover: unused credits carry forward
- True-ups: reconcile actual usage against commitment at period end
These should be explicit in contract logic, not ad hoc.
9. Design for observability and auditability
For every charge, be able to answer:
- What usage produced this charge?
- Which pricing rule was applied?
- Which version of the plan was active?
- Why was a discount applied?
- Why did the invoice total change?
Log and store:
- raw usage events
- aggregation outputs
- pricing decision traces
- invoice calculations
- payment attempts
- adjustment history
10. Practical system architecture
A common architecture:
- API ingestion service: accepts usage events
- Usage store: immutable event log
- Aggregation service: rolls up usage by customer/meter/period
- Pricing/rating engine: calculates charges
- Billing service: creates invoices and line items
- Payment service: charges cards, ACH, etc.
- Ledger service: tracks receivables, credits, balances
- Admin UI: manage plans, contracts, exceptions
Storage patterns:
- relational DB for contracts, invoices, line items, ledger
- event store or append-only table for usage
- job queue for async processing
11. Example data model
Minimum tables/entities:
customerssubscriptionsplansplan_versionsprice_componentsmetersusage_eventsusage_aggregatesinvoicesinvoice_line_itemspaymentscreditsadjustments
12. Implementation tips
- Keep pricing rules declarative if possible
- Use decimal arithmetic, not floating point
- Make billing period boundaries explicit
- Support time zones and currency rounding rules
- Build test fixtures for every plan type
- Create a simulation mode to preview invoices before launch
- Recompute invoices from source data, not stored totals alone
13. A simple hybrid billing flow
Example customer:
- $50 base monthly fee
- 5 seats included
- $12 per extra seat
- 1,000 API calls included
- $0.005 per extra API call
At month end:
- 8 seats → 3 extra × $12 = $36
- 1,420 API calls → 420 extra × $0.005 = $2.10
- Base fee = $50
- Total before tax = $88.10
14. What to build first
If you're starting from scratch, build in this order:
- Contract/pricing model
- Usage ingestion
- Aggregation
- Simple rating engine
- Invoice generation
- Payments
- Credits/discounts/tiers
- Reconciliation and reporting
15. Recommended MVP scope
For v1, support:
- monthly subscriptions
- one or two usage meters
- included allowances
- single overage rate
- invoice line items
- manual adjustment support
- payment collection
Then expand to:
- tiered pricing
- commitments
- proration
- taxes
- multi-currency
- usage-based discounts
If you want, I can also provide:
- a reference database schema
- a billing service API design
- or sample code for a rating engine in your preferred language.