0Pricing
Stripe Payments & SaaS Billing Systems · Lesson

Implementing Usage-Based Billing Systems

Design and integrate usage-based billing, where customers are charged based on their consumption of a service or resource.

Implementing Usage-Based Billing Systems is a free Stripe Payments & SaaS Billing Systems lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Stripe Payments & SaaS Billing Systems learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What is Usage-Based Billing?

Usage-based billing, also known as metered billing, charges customers based on how much they use a product or service.

Instead of a fixed monthly fee, customers pay only for their actual consumption. This model is popular for services like cloud storage, API calls, or data processing.

It offers flexibility and fairness, aligning costs directly with value received.

Core Concepts: Meters & Events

At the heart of usage-based billing are meters and events.

  • Meter: This is the specific resource or action you track. Examples include "API calls," "GB stored," or "minutes used."
  • Event: A single occurrence that increments your meter. Every time a user makes an API call, stores a file, or uses a minute, an "event" happens.

Your system needs to record and report these events.

Designing Your Usage Meter

When designing your usage-based system, first decide what to meter. What defines "usage" for your service?

  • Example: For a cloud storage service, your meter could be "gigabytes stored."
  • Granularity: How often do you report usage? Instantly? Hourly? Daily? Stripe typically aggregates usage over a billing cycle.

Clearly defining your meter ensures accurate billing.

Stripe's Metered Billing

Stripe supports usage-based billing through metered prices.

You define a product (e.g., "API Access") and then a price that specifies a cost "per unit" (e.g., $0.01 per API call). Instead of setting a fixed quantity for a subscription item, you report usage records to Stripe.

Stripe then aggregates these usage records over the billing period and charges the customer accordingly.

Product & Price Setup (Conceptual)

To set up usage-based billing in Stripe, you'd typically:

  1. Create a Product: This represents the service itself (e.g., "Cloud Storage").
  2. Create a Price: Link this price to your product. Crucially, set its recurring.usage_type to 'metered' and specify the unit_amount (cost per unit) or tiers for graduated pricing.

This tells Stripe that the price is based on reported usage.

Reporting Usage via API

Once your customer is subscribed to a metered price, you'll need to report their usage to Stripe using the API.

You'll send a Usage Record for a specific Subscription Item, indicating the quantity used. Stripe then adds this quantity to the customer's current billing cycle total.

This is usually done server-side from your application as usage events occur.

Code: Reporting Usage

Here's a simplified Java example showing how you might report usage to Stripe. You'd replace placeholders with your actual keys and IDs.

This example reports '10' units of usage for a specific subscription item.

import com.stripe.Stripe;
import com.stripe.exception.StripeException;
import com.stripe.model.UsageRecord;
import com.stripe.param.UsageRecordCreateParams;

public class Main {
  public static void main(String[] args) {
    Stripe.apiKey = "sk_test_YOUR_SECRET_KEY"; // Replace with your secret key

    String subscriptionItemId = "si_YOUR_SUBSCRIPTION_ITEM_ID"; // Get this from your subscription
    Long quantityToReport = 10L; // The amount of usage to report

    try {
      UsageRecordCreateParams params = UsageRecordCreateParams.builder()
        .setQuantity(quantityToReport)
        .setTimestamp(System.currentTimeMillis() / 1000L) // Current time in seconds
        .setAction(UsageRecordCreateParams.Action.INCREMENT) // Add to existing usage
        .build();

      UsageRecord usageRecord = UsageRecord.createOnSubscriptionItem(
        subscriptionItemId, params
      );

      System.out.println("Usage reported successfully: " + usageRecord.getId());
    } catch (StripeException e) {
      System.err.println("Error reporting usage: " + e.getMessage());
    }
  }
}

Billing Cycles & Aggregation

Stripe aggregates all usage records for a specific subscription item within a billing cycle.

When the billing cycle ends, Stripe calculates the total usage based on the configured aggregate_usage for that price. This total is then multiplied by the unit price (or applied to tiers) to determine the final charge for that period.

The invoice is then generated and finalized.

Different Aggregation Types

Stripe offers different ways to aggregate usage for a metered price:

  • sum: (Default) Adds up all reported usage quantities over the billing period. Perfect for API calls or data transfer.
  • max: Uses the highest reported usage quantity during the period. Useful for "peak usage" models, like concurrent users.
  • last_ever: Uses the last reported usage quantity. Great for "snapshot" billing, like storage used at the end of the period.

Choose the type that best fits your service.

Quick Check: Usage Billing

Which of the following scenarios is best suited for a 'last_ever' aggregation type in Stripe's usage-based billing?

Recap: Usage-Based Billing

You've learned how to design and implement usage-based billing with Stripe!

  • We covered the core concepts of meters and events.
  • Explored how Stripe uses metered prices and usage records.
  • Saw a code example for reporting usage via the API.
  • Understood different aggregation types like sum, max, and last_ever.

This model offers great flexibility for both you and your customers.

Frequently asked questions

Is the “Implementing Usage-Based Billing Systems” lesson free?

Yes — the full text of “Implementing Usage-Based Billing Systems” is free to read here on the web, and the Stripe Payments & SaaS Billing Systems course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Stripe Payments & SaaS Billing Systems course, upgrade to CoddyKit PRO.

What will I learn in “Implementing Usage-Based Billing Systems”?

Design and integrate usage-based billing, where customers are charged based on their consumption of a service or resource. You practise Stripe Payments & SaaS Billing Systems with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Stripe Payments & SaaS Billing Systems?

No prior experience is required. Stripe Payments & SaaS Billing Systems on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Implementing Usage-Based Billing Systems” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Stripe Payments & SaaS Billing Systems lesson?

Yes. Every Stripe Payments & SaaS Billing Systems lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Implementing Usage-Based Billing Systems
  2. Configuring Seat-Based and Tiered Pricing
  3. Custom Billing Cycles and Schedules
  4. Volume and Graduated Pricing Tiers in Depth
← Back to Stripe Payments & SaaS Billing Systems