Skip to main content

​
Work with Limited-Type Metric (Limit Metered)

The Limit Metered metric type is used to track user usage and prevent overconsumption. This metric type provides a hard reset each billing cycle, meaning unused quota is lost when the period ends.

​
Key Characteristics

  • ✅ Hard Reset: Usage resets completely at the start of each billing cycle
  • ✅ No Carryover: Unused quota is lost at the end of each period
  • ✅ Automatic Rejection: System rejects requests when limit is reached
  • ✅ Predictable Budgets: Customers stay within their plan limits

​
When to Use Limit Metered

Perfect for:
  • Monthly allowances that should reset completely
  • Time-sensitive quotas (e.g., “1000 API calls per month”)
  • Features where unused quota doesn’t have value
  • Scenarios requiring a fresh start each billing cycle
Example: “1000 API calls per month” - unused calls don’t carry over

​
Limit Metered vs Limit Recurring

AspectLimit MeteredLimit Recurring
Reset BehaviorHard reset (complete)Soft reset (with carryover)
Quota LossUnused quota is lostUnused quota is preserved
Use CaseMonthly fresh startsPrepaid credits
Example”1000 API calls/month""1000 SMS credits/month”
💡 Need quota carryover? See Limit Recurring Metric for metrics that preserve unused quota.
The metric system integrates with the UniBee API, which provides event-based statistics. You can report usage data by sending events to the Event API. The metric counting for each product, you may need specified for the productId at Event API, default product will used if not specified Aggregation Type of Count metric event, it increases 1 usage number 
curl --location --request POST "$UniBee_API_Host/merchant/merchant_metric/merchant_metric_event" \
  --header "Authorization: Bearer $YOUR_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "metricCode": "folder_count_limit", // code needs to be configured in advance in the UniBee portal
    "externalUserId": "$YOUR_USER_ID",
    "externalEventId": "string", // string, **unique**, e.m. [folderId]
    "metricProperties": {}
}'
same externalEventId , no double counting Aggregation Type of Latest metric event, it Inspect 5, event of Latest type will not be add up 
curl --location --request POST "$UniBee_API_Host/merchant/merchant_metric/merchant_metric_event" \
  --header "Authorization: Bearer $YOUR_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "metricCode": "active_profile_limit", // code needs to be configured in advance in the UniBee portal
    "externalUserId": "$YOUR_USER_ID",
    "externalEventId": "string", // string, **unique**, e.m. [folderId]
    "metricProperties": {
      "active_profile": 5
    }
}'
if this metricCode is Aggregation Type of Sum, 5 will be add up to the current value Normally, if the user has a subscription, the event interface returns the current value (based on the aggregation type) and the limit value for the user 
{
  "code": 0,
  "message": "",
  "data": {
    "merchantMetricEvent": {
      "id": 15685,
      "merchantId": 15621,
      "metricCode": "active_profile_limit",
      "externalEventId": "req20240223yuUd7wHU7k8Cz2Fs",
      "createTime": 1708667871,
      "subscriptionIds": "sub202402236DygwtxKvLE1zN2",
      "subscriptionPeriodStart": 1708658304,
      "subscriptionPeriodEnd": 1708744704,
      "metricLimit": 5,
      "used": 2
    }
  },
  "redirect": "",
  "requestId": "req20240223DYIVhsEzTXykZEE"
}
When the user reaches the upper limit value set-up at Plan definision page, the event interface will return an error message (such as “reject”)to inform Multilogin that the usage has reached the upper limit. 
{
  "code": 51,
  "message": "metric limit reached, current used: 10, limit: 10",
  "data": {},
  "redirect": "",
  "requestId": "req20240223rmNJQOnggAuYpPd"
}

​
Limit Boundary Behavior

The system uses a boundary-inclusive check: when the usage plus the new event value equals the limit, the event is allowed. When it exceeds the limit, the event is rejected. Examples:
  • Limit = 100, Current Used = 90, Event Value = 10 → ✅ Allowed (90 + 10 = 100 ≤ 100)
  • Limit = 100, Current Used = 90, Event Value = 11 → ❌ Rejected (90 + 11 = 101 > 100)
  • Limit = 100, Current Used = 100, Event Value = 0 → ✅ Allowed (100 + 0 = 100 ≤ 100)
  • Limit = 100, Current Used = 100, Event Value = 1 → ❌ Rejected (100 + 1 = 101 > 100)

​
Plan Limit Deletion Behavior

​
Important: Plan Limit Must Be Configured

Limit Metered metrics require a Plan Limit to be configured. If the Plan Limit is deleted or not configured, all events will be rejected, even if quota adjustments exist. Behavior when Plan Limit is deleted:
  1. Without Quota Adjustments:
    • All events are rejected
    • Error message: "metric limit reached, current used: X, limit: 0"
    • limit: 0 indicates that no Plan Limit is configured
  2. With Quota Adjustments:
    • Quota adjustments do not take effect when Plan Limit is deleted
    • All events are rejected
    • Error message: "metric limit reached, current used: X, limit: 0"
Why this behavior?
  • Limit types (Limit Metered, Limit Recurring) require a limit binding to function correctly
  • Without a Plan Limit, the system cannot determine the usage boundary
  • This prevents unlimited event creation that could cause unexpected behavior
To resolve:
  • Ensure the Plan Limit is properly configured in the plan definition
  • If you need to temporarily disable the metric, consider archiving the plan or removing the metric from the plan instead of deleting the Plan Limit
All the metric value will be reset to 0 when the user’s subscription enters into the new billing cycle. Important: With Limit Metered, any unused quota is lost when the billing cycle ends. For example:
  • Month 1: Plan includes 1000 units, user uses 800
  • Month 2: Plan resets to 1000 units (the 200 unused units from Month 1 are lost)
If you need unused quota to carry over, use Limit Recurring instead. Event also can be revoked in the same subscription period by API UniBee API, and relative usage will be revoked as well.