Usage-Based Billing
A billing model where customers are charged based on their actual consumption of resources or API calls, tracked via usage records reported to the billing system.
Description
Usage-based billing charges customers proportionally to their actual consumption rather than a flat recurring fee. In Stripe, this is implemented using metered Prices on subscriptions. You create a Price with recurring.usage_type set to 'metered' and define the per-unit cost and aggregation strategy (sum, last_during_period, last_ever, or max). Throughout the billing period, your application reports usage increments via stripe.subscriptionItems.createUsageRecord(), and Stripe tallies the total at period end to generate the invoice.
The critical engineering challenge is accurately and reliably tracking usage. Your system needs a durable usage tracking pipeline that can handle high-throughput events (API calls, compute minutes, storage bytes) without data loss or double-counting. A common pattern is to buffer usage events in a time-series store or message queue, aggregate them periodically (e.g., every hour), and batch-report to Stripe. The usage record's timestamp and action ('increment' vs 'set') parameters determine how Stripe aggregates records; using 'increment' is safer for distributed systems where multiple workers may report concurrently.
Hybrid billing models combine a base subscription fee with metered overage charges. For example, a plan might include 10,000 API calls per month with each additional call billed at $0.001. This is modeled in Stripe as a subscription with two line items: a fixed-price item for the base fee and a metered-price item with graduated or volume-based tiers for the usage component.
Prompt Snippet
Configure metered billing with stripe.prices.create() using recurring.usage_type: 'metered' and billing_scheme: 'tiered' with tiers for graduated pricing (e.g., first 10K requests free, $0.001/request after). Report usage hourly via stripe.subscriptionItems.createUsageRecord() with action: 'increment' and an idempotency key derived from the subscription_item_id + hour timestamp to prevent double-reporting. Build a usage aggregation pipeline using a time-series table (user_id, metric, quantity, period_start) that serves as the source of truth, with a cron job syncing totals to Stripe before invoice finalization.
Tags
Related Terms
Subscription Billing (Stripe)
Managing recurring payment cycles using Stripe's Subscription and Price APIs, including plan creation, billing intervals, upgrades/downgrades, and lifecycle event handling.
Invoice Generation
Creating and managing invoices for one-time charges and subscription billing cycles, including line item customization, tax itemization, and PDF generation through Stripe's Invoice API.
Payment Analytics & Reporting
Tracking and reporting on key financial metrics including MRR, churn rate, LTV, payment success rates, and revenue breakdowns to understand business health and inform decisions.
Ledger / Transaction Log Design
Designing an append-only transaction log that records every financial event with double-entry bookkeeping principles, providing a complete audit trail and enabling balance reconciliation.