How to implement usage based billing on Stripe

intermediate 12 min read Updated 2026-03-18

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.

Try Stripe Full Stripe Review

Prerequisites

Active Stripe account with API keys
Basic understanding of webhooks
Development environment with API access
Product catalog already created

Step-by-Step Instructions

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.

Choose 'Sum usage during period' for cumulative billing like API calls, or 'Most recent usage' for capacity-based billing like storage.

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.

Set up a base subscription fee alongside metered billing by adding both fixed and metered price items to the same subscription.

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'
  }
);

Track usage events in real-time or batch them for periodic reporting.

Use 'increment' action for adding usage and 'set' action for absolute values. Always include accurate timestamps for proper billing periods.

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.

Monitor the 'Upcoming invoice' preview to see how usage will be billed before the actual invoice generation.

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.

Always verify webhook signatures in your endpoint to ensure requests are from Stripe and handle idempotency for duplicate events.

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)

Check Billing > Usage records to verify data appears correctly. Create a test invoice preview to confirm usage calculations.

Use Stripe's test mode to validate your entire usage billing flow before switching to live mode with real customers.

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.

Implement usage alerts for customers approaching billing thresholds to improve transparency and reduce payment disputes.

Common Issues & 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.

Prices mentioned in this guide are pulled from current plan data and may change. Always verify on the official Stripe website before purchasing.

Visit Stripe View Stripe Pricing