> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unibee.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Work with Limited-Type Metric (Limit Metered)

> Ideal for fixed-price plans, this metric type ensures that customers do not incur unexpected charges. When the predefined usage limit is reached, the system automatically rejects any further requests, keeping usage within budget.

# 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

| Aspect             | Limit Metered          | Limit Recurring             |
| ------------------ | ---------------------- | --------------------------- |
| **Reset Behavior** | Hard reset (complete)  | Soft reset (with carryover) |
| **Quota Loss**     | Unused quota is lost   | Unused quota is preserved   |
| **Use Case**       | Monthly fresh starts   | Prepaid credits             |
| **Example**        | "1000 API calls/month" | "1000 SMS credits/month"    |

> 💡 **Need quota carryover?** See [Limit Recurring Metric](./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](/api-reference/metric-event/new-merchant-metric-event).

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

```shellscript theme={null}
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

```shellscript theme={null}
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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](./limit-recurring-metric) instead.

Event also can be revoked in the same subscription period by API UniBee API, and relative usage will be revoked as well.