Transform raw usage events into billable quantities with aggregation and filtering.
Meters convert raw events into billable quantities. They filter events and apply aggregation functions (Count, Sum, Max, Last) to calculate usage per customer.
Unit label for invoices. Examples: calls, tokens, GB, hours
3
Filtering (Optional)
Add conditions to filter which events are counted:
AND logic: All conditions must match
OR logic: Any condition can match
Comparators: equals, not equals, greater than, greater than or equals, less than, less than or equals, contains, does not containEnable filtering, choose logic, add conditions with property key, comparator, and value.
By default, meters charge customers per-unit in dollars (or your configured currency). You can instead configure a meter to deduct from a credit balance - so usage consumes credits rather than generating a monetary charge.
Credit-based deduction requires a Credit Entitlement attached to the same product. Create your credit first, then link it to the meter.
First, create a credit in Products → Credits. Define the unit (e.g., “API Calls”, “Tokens”), precision, and lifecycle settings (expiry, rollover, overage).See the Credit-Based Billing guide for detailed instructions.
2
Create or Edit a Usage-Based Product
Go to your usage-based product and open the Meter configuration section.
3
Add a Meter
Click the + button to attach a meter. Configure the event name, aggregation type, and measurement unit as usual.
4
Enable 'Bill Usage in Credits'
Toggle Bill usage in Credits on the meter configuration. This reveals the credit settings:
Toggle 'Bill usage in Credits' to switch from currency-based to credit-based deduction.
The number of usage units required to deduct 1 credit. For example:
1 = each meter event deducts 1 credit
100 = 100 meter events deduct 1 credit
1000 = 1,000 API calls consume 1 credit
5
Set the Free Threshold
The Free Threshold still applies - events below this threshold don’t deduct credits.Example: With a free threshold of 1,000 and meter-units-per-credit of 1:
Customer uses 2,500 API calls
First 1,000 are free
Remaining 1,500 deduct 1,500 credits from their balance
Once configured, the deduction pipeline runs automatically:
Events arrive - Your application sends usage events via the Event Ingestion API
Meter aggregates - Events are aggregated per your meter configuration (Count, Sum, Max, Last)
Background worker processes - Every minute, a worker fetches new events since the last checkpoint
Credits are deducted - Aggregated usage is converted to credits using the meter_units_per_credit rate and deducted using FIFO ordering (oldest grants consumed first)
Overage tracked - If the balance hits zero and overage is enabled, usage continues and overage is handled according to the configured behavior (forgiven at reset, billed at next invoice, or carried forward as deficit)
Credit deduction runs asynchronously (every ~1 minute). There may be a brief delay between event ingestion and balance deduction. Design your application to handle this delay - don’t rely on real-time balance checks for access control on individual requests.
You can link multiple meters on the same product to the same credit entitlement. All meters deduct from one shared balance.Example: An AI platform with two meters:
text.generation - 1 credit per 1,000 tokens
image.generation - 10 credits per image
Both deduct from the same “AI Credits” pool. The customer sees a single unified balance in their portal.
Use different meter_units_per_credit rates across meters to express relative costs. Expensive operations (image generation) cost fewer meter units per credit than cheap ones (text completion).
List Customer Ledger
View the full credit deduction history for a customer.
Get Customer Balance
Check a customer’s current credit balance via API.
