Skip to main content
Billable metrics define what you measure in your product. Every unit of consumption — tokens, compute hours, storage, API calls — starts as a metric.

​
Core Concepts

A billable metric is a measurable unit. It doesn’t have a price — that comes later when you create plans. It can also be used independently of billing, purely for metering and entitlement enforcement. Each metric belongs to exactly one product and specifies:
  • Name — What customers see (e.g., “Input Tokens”, “GPU Hours”)
  • Unit — How it’s measured (e.g., “tokens”, “hours”, “GB”)
  • Aggregation — How to combine usage values over a period

​
How Metrics Work

Billable metrics track variable consumption through events. Perfect for:
  • LLM tokens processed
  • Compute hours consumed
  • Data transferred
  • Queries executed
You report usage via events, and Paygentic aggregates it per billing period or entitlement window.
For fixed charges like platform fees, subscriptions, or setup costs, use Fees instead of billable metrics.

​
Aggregation Types

Specify how raw event values are combined when calculating usage:
AggregationDescription
sumTotal of all values in the period
countNumber of events, regardless of value
avgMean of all values
minSmallest value recorded
maxLargest value recorded
unique_countCount of distinct values (e.g., unique user IDs)
latestMost recent value (useful for gauge-style metrics)

​
Meter Configuration

To receive meter events, a billable metric needs three additional fields that define how it reads from the event stream:

​
eventType

The type value your events carry. Only events with a matching type field contribute to this metric. 
eventType: "ai.inference"

​
valueProperty

A JSONPath expression pointing to the numeric value inside the event data payload. Required for all aggregations except count.
PathExtracts
$.tokensTop-level tokens field
$.usage.inputTokensNested field via dot notation

​
groupBy

A map of dimension names to JSONPath expressions. Allows slicing usage by properties like model, region, or tier. 
{
  "model": "$.model",
  "region": "$.region"
}
Full example: a billable metric for AI inference, aggregating token usage and allowing breakdowns by model: 
{
  "name": "AI Tokens",
  "unit": "tokens",
  "aggregation": "SUM",
  "eventType": "ai.inference",
  "valueProperty": "$.tokens",
  "groupBy": {
    "model": "$.model"
  }
}
Multiple billable metrics can share the same eventType. Each extracts a different valueProperty from the same events. This lets you track input and output tokens separately while sending a single event per inference.

​
Real-World Examples

LLM Service Separate input and output for different pricing:
  • Metric: “Input Tokens” — eventType: "ai.inference", valueProperty: "$.inputTokens", aggregation: sum
  • Metric: “Output Tokens” — eventType: "ai.inference", valueProperty: "$.outputTokens", aggregation: sum
  • Metric: “Fine-tuning Hours” — eventType: "training.job", valueProperty: "$.durationHours", aggregation: sum
Data Platform Track different resource types:
  • Metric: “Storage” — eventType: "storage.usage", valueProperty: "$.gbHours", aggregation: sum
  • Metric: “Compute” — eventType: "compute.usage", valueProperty: "$.vcpuHours", aggregation: sum
  • Metric: “Queries” — eventType: "query.executed", aggregation: count
Video Processing Measure processing and delivery:
  • Metric: “Minutes Processed” — eventType: "video.transcode", valueProperty: "$.durationMinutes", aggregation: sum
  • Metric: “Bandwidth” — eventType: "video.delivery", valueProperty: "$.transferGB", aggregation: sum

​
Reporting Usage

Once metrics are defined, report usage by sending meter events. See Meter Events for the full ingestion guide, including multi-dimensional metering and idempotency.

​
Next Steps

After defining metrics:
  1. Send meter events to start recording usage
  2. Create plans to group your offerings
  3. Set prices for each metric