Sign in →

Billable Units

Define what you charge for — API calls, tokens, sessions, storage, or any custom metric — with Aforo's billable units system.

Updated 2026-06-15Suggest edits

Billable Units

Billable Units (internally called metrics) define what you charge for. They are the atomic measurement unit that your usage events report against and your rate plans price.

Every charge in Aforo traces back to a billable unit — whether that's an API call, an LLM token, an active session, GB of storage, or a custom dimension you define.

Built-in Templates

Aforo ships with pre-built templates for each product type:

Standard API

UnitAggregationDescription
API CallsCOUNTTotal HTTP requests
Response SizeSUMOutbound bytes
Request SizeSUMInbound bytes
Latency P95PERCENTILE_95Tail latency tracking

AI Agent

UnitAggregationDescription
Input TokensSUMPrompt tokens consumed
Output TokensSUMCompletion tokens generated
Agent SessionsCOUNTDistinct invocations
Tool CallsCOUNTExternal tool invocations

MCP Server

UnitAggregationDescription
Tool InvocationsCOUNTMCP tools/call requests
Session DurationSUMActive session seconds
Active SessionsUNIQUEConcurrent sessions
Unique AgentsUNIQUEDistinct agent identities

Agentic API

UnitAggregationDescription
Agent InvocationsCOUNTAPI calls from agents
Workflow StepsCOUNTMulti-step sequence steps
Context Window SizeSUMToken context consumed
Execution DurationSUMWorkflow run milliseconds

Aggregation Types

TypeDescriptionExample
COUNTNumber of eventsAPI calls
SUMTotal of a numeric fieldBytes transferred
UNIQUEDistinct valuesUnique users
MAXPeak valueMax concurrent connections
AVGRunning averageAverage latency
PERCENTILE_9595th percentileP95 response time

Custom Billable Units

Create a custom unit when a template doesn't fit your pricing model:

  1. Go to Catalog → Billable Units
  2. Click + New Billable Unit
  3. Set:
    • Name — e.g. "Compute Minutes"
    • Unit Label — e.g. "minutes"
    • Aggregation — how events roll up (COUNT, SUM, UNIQUE, etc.)
    • Event Field — the numeric field from your event payload to aggregate
    • Product Types — which product types can use this unit
⚠

You cannot change a unit's aggregation type after it has been used in a rate plan. Create a new unit if you need a different aggregation method.

Filtering

Custom units support filter conditions to narrow which events count. For example, only count API calls where status_code < 400:

{
  "filterConditions": [
    {
      "field": "status_code",
      "operator": "LESS_THAN",
      "value": "400"
    }
  ]
}

Supported operators: EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN, CONTAINS, NOT_CONTAINS, IN, NOT_IN

Product Associations

Billable units can be associated with multiple products (M:N relationship). A unit like "Input Tokens" can price both your AI Agent product and your Agentic API product.

Deletion Protection

Like products, billable units are protected from deletion when used in active rate plans. The check returns ALLOW, WARN, or BLOCK — and BLOCK requires migrating subscribers before proceeding.

Bulk Operations

Bulk Create from Templates

curl -X POST https://catalog.aforo.ai/api/v1/metrics/bulk \
  -H "Authorization: Bearer $AFORO_API_KEY" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -d '{ "productType": "AI_AGENT" }'

This seeds all 8 standard templates for AI Agent in one call.

Export / Import

Export all active units for backup or migration:

curl https://catalog.aforo.ai/api/v1/metrics/export \
  -H "Authorization: Bearer $AFORO_API_KEY" \
  -H "X-Tenant-Id: $TENANT_ID" > units.json

Import into another tenant with skipDuplicates: true to avoid conflicts.