Skip to main content
Usage-based billing allows you to charge customers based on their actual consumption of your product or service, rather than fixed recurring fees. Polar’s usage-based billing system provides real-time tracking, flexible pricing models, and automatic invoicing.

​
How It Works

The usage-based billing system follows a simple workflow:
1

Send Events

Your application sends usage events to Polar whenever a billable action occurs (API calls, storage used, tokens consumed, etc.)
2

Meters Aggregate Events

Meters filter and aggregate events based on your configuration to calculate consumption
3

Credits Control Access

Customer meters track credited units (prepaid or included) vs. consumed units to control access
4

Billing & Invoicing

At the end of each billing cycle, consumption is calculated and invoiced automatically

​
Key Concepts

​
Events

Events represent billable actions in your system. Each event contains:
  • Timestamp: When the action occurred
  • Customer ID: Who performed the action
  • Name: Type of event (e.g., api.request, storage.used)
  • Metadata: Additional context (e.g., tokens consumed, file size)
Polar supports two types of events:
  • User events: Created by your application via the API
  • System events: Created automatically by Polar (subscriptions, credits, etc.)

​
Meters

Meters define how to measure consumption by:
  1. Filtering events to include only relevant ones
  2. Aggregating events to calculate a quantity
Example: A meter could count all api.request events where metadata.model = "gpt-4" and sum the metadata.tokens field.

​
Customer Meters

Customer meters track the balance for each customer:
  • Credited Units: Prepaid credits or included allowance
  • Consumed Units: Actual usage measured by the meter
  • Balance: Remaining credits (credited - consumed)
You can use the balance to control access to your product.

​
Billing Entries

Billing entries are created for metered consumption during a billing period. They represent:
  • The time period (start and end timestamps)
  • The consumed units
  • The applicable price
  • The calculated amount to charge

​
Pricing Models

Polar supports flexible metered pricing:

​
Per-Unit Pricing

Charge a fixed amount per unit consumed: 
Price: $0.01 per API call
Usage: 1,000 calls
Charge: $10.00

​
Tiered Pricing

Different rates for different usage levels: 
First 1,000 calls: $0.01 each
Next 9,000 calls: $0.008 each
10,000+ calls: $0.005 each

​
Volume Pricing

Rate applies to all units based on total volume: 
0-1,000 calls: $0.01 each (total)
1,001-10,000 calls: $0.008 each (total)
10,000+ calls: $0.005 each (total)

​
Aggregation Functions

Meters support multiple aggregation functions:
FunctionDescriptionExample Use Case
countCount matching eventsAPI requests, transactions
sumSum a numeric propertyTotal tokens, total GB
maxMaximum value observedPeak concurrent users
minMinimum value observedLowest latency
avgAverage valueAverage response time
uniqueCount unique valuesUnique users, unique IPs

​
Common Use Cases

​
API Usage

Charge based on API calls, categorized by endpoint or model: 
{
  "name": "api.request",
  "customer_id": "cus_...",
  "metadata": {
    "endpoint": "/v1/chat",
    "model": "gpt-4",
    "tokens": 1250
  }
}

​
Storage & Bandwidth

Track storage usage and data transfer: 
{
  "name": "storage.snapshot",
  "customer_id": "cus_...",
  "metadata": {
    "bytes": 5368709120,
    "type": "backup"
  }
}

​
Compute Resources

Measure compute time, memory, or other resources: 
{
  "name": "compute.job",
  "customer_id": "cus_...",
  "metadata": {
    "duration_seconds": 3600,
    "cpu_cores": 4,
    "memory_gb": 16
  }
}

​
Seats & Licenses

Track active users or seats: 
{
  "name": "user.active",
  "customer_id": "cus_...",
  "member_id": "mem_...",
  "metadata": {
    "email": "[email protected]",
    "role": "admin"
  }
}

​
Credit System

The credit system provides flexibility for prepaid and included usage:

​
Included Credits

Include credits with subscriptions as benefits:
  • Set up a “Meter Credit” benefit on your product
  • Specify number of units and whether they rollover
  • Credits are automatically added when subscription starts
  • Credits reset each billing cycle (unless rollover is enabled)

​
Prepaid Credits

Sell prepaid credit packs:
  • Create a one-time product with meter credits
  • Customer purchases credits upfront
  • Credits are applied to their meter balance
  • Use for top-ups or pay-as-you-go models

​
Rollover

Control whether unused credits carry forward:
  • Rollover enabled: Unused credits accumulate
  • Rollover disabled: Credits reset each cycle

​
Workflow Example

Here’s a complete example of usage-based billing in action:
1

Customer subscribes

Customer subscribes to “Pro Plan” which includes:
  • 10,000 API credits per month
  • Metered billing at $0.001 per additional call
2

Credits are added

Polar automatically creates a meter.credited event adding 10,000 units to the customer’s meter
3

Customer uses your API

Your application sends events as the customer makes API calls:
{ "name": "api.request", "customer_id": "cus_..." }
4

Consumption is tracked

The meter aggregates events in real-time:
  • Consumed: 12,500 calls
  • Credited: 10,000 calls
  • Balance: -2,500 calls (overage)
5

Billing entry is created

Polar creates a billing entry for the overage:
  • 2,500 units × 0.001=0.001 = 2.50
6

Invoice is generated

At billing cycle end, an invoice is created:
  • Pro Plan subscription: $49.00
  • Additional API calls (2,500 × 0.001):0.001): 2.50
  • Total: $51.50
7

Meter resets

After invoicing, the meter resets and new credits are added for the next cycle

​
Best Practices

​
Event Design

  • Use descriptive names: api.request instead of request
  • Include relevant metadata: Add context needed for filtering and aggregation
  • Keep events atomic: One event per billable action
  • Use timestamps correctly: Set timestamp to when action occurred, not when event was sent

​
Meter Configuration

  • Start simple: Begin with basic count aggregations
  • Test filters thoroughly: Ensure events match as expected
  • Consider granularity: Balance detail with simplicity
  • Document your meters: Explain what each meter measures

​
Credit Management

  • Set appropriate limits: Match included credits to your pricing model
  • Consider rollover carefully: Rollover increases goodwill but reduces revenue
  • Monitor balances: Alert customers before they run out
  • Provide visibility: Show customers their usage and balance

​
Performance

  • Batch events when possible: Send multiple events in one request
  • Use deduplication: Set external_id to prevent duplicate billing
  • Monitor ingestion rate: Stay within API rate limits
  • Cache meter balances: Don’t query on every request

​
Next Steps

Event Ingestion

Learn how to send usage events to Polar

Meters

Configure meters to measure consumption

Credits

Set up credit benefits and prepaid packs

Billing

Understand billing cycles and invoicing

Build docs developers (and LLMs) love

Get started for freeTalk to us