Intermediate
How to implement usage based billing on Stripe
Quick Answer
Usage-based billing on Stripe requires creating metered products with usage records that track consumption. You'll set up subscription items with metered billing, report usage via API calls, and configure automated invoicing.
Prerequisites
- Active Stripe account with API keys
- Basic understanding of webhooks
- Development environment with API access
- Product catalog already created
1
Create a metered product and price
Navigate to Products in your Stripe Dashboard and click Add product. Enter your product name and description. Under Pricing model, select Usage is metered. Set your Price per unit and choose Sum usage during period or Most recent usage during period for aggregation. Click Save product.
Tip
Choose 'Sum usage during period' for cumulative billing like API calls, or 'Most recent usage' for capacity-based billing like storage.
2
Set up the subscription with metered items
Go to Customers and select your customer or create a new one. Click Create subscription and add your metered product. Leave the Quantity field empty for metered items. Configure your Billing cycle (monthly recommended for usage billing). Under Collection method, select Charge automatically and click Start subscription.
Tip
Set up a base subscription fee alongside metered billing by adding both fixed and metered price items to the same subscription.
3
Implement usage tracking in your application
Install the Stripe library for your platform and configure API authentication. Create usage records using the API:
stripe.subscriptionItems.createUsageRecord(
'si_subscription_item_id',
{
quantity: 100,
timestamp: Math.floor(Date.now() / 1000),
action: 'increment'
}
);Tip
Use 'increment' action for adding usage and 'set' action for absolute values. Always include accurate timestamps for proper billing periods.
4
Configure usage aggregation and billing
In your product settings, verify the Usage aggregation method matches your billing model. Go to Billing > Subscriptions and click on your subscription. Under Items, confirm the metered item shows Pending usage. Set Proration behavior to Create prorations if you want mid-cycle usage billing.
Tip
Monitor the 'Upcoming invoice' preview to see how usage will be billed before the actual invoice generation.
5
Set up webhook endpoints for usage events
Navigate to Developers > Webhooks and click Add endpoint. Enter your endpoint URL and select these events:
invoice.created, invoice.payment_succeeded, invoice.payment_failed, and customer.subscription.updated. Click Add endpoint and note your webhook signing secret for verification.Tip
Always verify webhook signatures in your endpoint to ensure requests are from Stripe and handle idempotency for duplicate events.
6
Test usage reporting and billing
Submit test usage records using your API integration or Stripe CLI:
stripe usage-records create \
--subscription-item=si_test_item \
--quantity=50 \
--timestamp=$(date +%s)Tip
Use Stripe's test mode to validate your entire usage billing flow before switching to live mode with real customers.
7
Monitor and optimize usage billing
Set up monitoring in Billing > Revenue recognition to track usage revenue. Use the Reporting section to analyze usage patterns and revenue trends. Configure Smart retries under Settings > Billing for failed usage-based payments. Set up alerts for unusual usage spikes or billing failures.
Tip
Implement usage alerts for customers approaching billing thresholds to improve transparency and reduce payment disputes.
Troubleshooting
Usage records not appearing on invoices
Verify the timestamp falls within the current billing period and the subscription item ID is correct. Check that usage aggregation is set to sum not last_during_period for cumulative billing.
Duplicate usage charges appearing
Implement idempotency keys when creating usage records:
idempotency_key: 'usage_' + unique_event_id. Check your webhook handling doesn't create duplicate records from retry events.Customer invoices showing zero usage
Confirm usage records are submitted before the billing period ends. Check the subscription item status is active and verify API authentication has correct permissions for usage record creation.
Usage billing amounts incorrect
Review your price aggregation method in the product settings. Verify unit prices match your pricing model and check for timezone issues in timestamp calculations that might assign usage to wrong billing periods.
Ready to get started with Stripe?
Put this tutorial into practice. Visit Stripe and follow the steps above.
Visit Stripe →