Skip to main content
#How To Create A UniBee Billable Metric

​
1. Overview

The Billing Metric module allows you to define and track billable business metrics such as API requests, storage usage, or AI token consumption.
The redesigned interface introduces template-based configuration, real-time previews, and clear contextual guidance to make metric setup faster and more intuitive.

​
🎯 Key Benefits

  • Lower learning curve – friendly field names and contextual explanations
  • Faster onboarding – quick-start templates for common billing use cases
  • Instant validation – live event and aggregation previews
  • Standardized model – consistent flow: Event → Metric → Aggregation → Billing

​
2. Navigation

Access this module from the sidebar:
Product → Billable Metric
The main list view displays all existing metrics, including:
  • Metric Name & Code
  • Aggregation Type (Count / Sum / Max / Unique)
  • Charge Type (Charge Metered / Charge Recurring)
  • Last Updated
  • Actions (✏️ Edit / 🗑 Delete)

​
3. Create a New Metric

Click “+ New Metric” to open the metric creation page.

​
3.1 Quick Templates

Predefined templates are provided for common billing scenarios.
Selecting a template will auto-fill key fields, but you can freely modify them.
TemplatePurposeAggregationUnit
API RequestsTrack API callsCountrequests
LLM TokensTrack token usageSumtokens
Worker DurationTrack task durationSumms
Storage GBTrack storage usageMaxGB
Emails SentTrack sent emailsCountemails
Unique UsersTrack active usersUniqueusers
CustomFully blank configurationanycustom

​
3.2 Basic Information

FieldDescriptionRequired
NameHuman-readable name (e.g. API Requests)✅
Code / SlugUnique identifier generated from the name (editable)✅
DescriptionOptional explanation of the metric purpose
Metric TypeSee Metric Types Guide below✅
UnitUnit of measure (e.g. requests, tokens, GB, ms)✅
💡 The Slug auto-generates from the Name and must be unique.

​
3.2.1 Metric Type Selection

When creating a metric, you must choose one of four metric types. This choice determines how usage is tracked and billed:

​
Limit Metered

  • Behavior: Usage resets completely at the start of each billing cycle
  • Quota: Hard limit that rejects requests when exceeded
  • Carryover: No - unused quota is lost
  • Best For: Monthly allowances that reset (e.g., “1000 API calls per month”)
Example: 
Month 1: 1000 units, used 800 → 200 unused (lost)
Month 2: 1000 units (fresh start)

​
Limit Recurring ⭐

  • Behavior: Usage resets, but unused quota carries over
  • Quota: Soft limit with automatic carryover
  • Carryover: Yes - unused quota is preserved
  • Best For: Prepaid credits (e.g., “1000 SMS credits per month”)
Example: 
Month 1: 1000 units, used 700 → 300 unused (carries over)
Month 2: 1000 base + 300 carryover = 1300 units total

​
Charge Metered

  • Behavior: Usage resets each cycle, charges based on consumption
  • Billing: Additional charges added to invoice at period end
  • Reset: Yes - usage resets to zero each period
  • Best For: Pay-per-use services (e.g., “$0.10 per API call”)
Example: 
Month 1: User makes 500 calls × $0.10 = $50 added to invoice
Month 2: Usage resets, new billing cycle starts

​
Charge Recurring

  • Behavior: Usage accumulates continuously across periods
  • Billing: Charges based on total accumulated usage
  • Reset: No - usage never resets
  • Best For: Cumulative usage billing (e.g., total data usage)
Example: 
Month 1: 100 GB used
Month 2: +50 GB (total: 150 GB)
Month 3: +75 GB (total: 225 GB)

​
Quick Decision Guide

NeedRecommended Type
Monthly quota that resets completelyLimit Metered
Prepaid credits that accumulateLimit Recurring
Pay-per-use billingCharge Metered
Cumulative/lifetime usageCharge Recurring
💡 Not sure which type to choose? See the detailed comparison in What is Billable Metric? for more examples.

​
3.3 Event & Aggregation

FieldDescription
AggregationDefines how data is summarized: Count / Sum / Max / Min / Unique Count
Value PropertyNumeric field path, required for Sum/Max/Min types
Distinct ByUsed for Unique Count (e.g. user_id)
Labels to Group BySplit usage by dimensions (e.g. region, plan, customer_id)

​
Right-Side Preview Panel

  • Event Example: Live JSON event structure based on your form inputs
  • Aggregation Preview: Displays example calculations (e.g. 1 + 2 + 3 = 6 or max(10, 20, 30) = 30)
  • Quick Snippet: Auto-generated cURL / SDK example for developer use
  • Test It: Simulate an event and preview real-time calculation results
Highlight the right-side panels in color (Event Example – green, Aggregation Preview – blue, Quick Snippet – yellow).

​
4. API Integration — New Merchant Metric Event

Developers can send event data to UniBee Event API for automatic metric aggregation and billing.

​
Endpoint