​

Work with Limit Recurring Metric

​

Overview

​

Key Features

• ✅ Automatic Carryover: Unused quota automatically transfers to the next billing cycle
• ✅ Quota Accumulation: Quota can accumulate over time if not fully used
• ✅ Manual Adjustments: Administrators can manually adjust quota for compensation or corrections
• ✅ Transparent Tracking: Complete breakdown showing quota sources (base plan, carryover, manual adjustments)

​

How It Works

​

Basic Concept

• Each billing cycle, you receive your base quota from the plan
• Any unused quota from the previous cycle automatically carries over
• Total available quota = Base quota + Carried over quota

​

Example: Monthly SMS Credits

Month 1 (January)
├─ Base Quota: 1000 SMS credits (from plan)
├─ Used: 700 SMS
└─ Remaining: 300 SMS

↓ Billing Cycle Renews (Automatic Carryover)

Month 2 (February)
├─ Base Quota: 1000 SMS credits (from plan)
├─ Carried Over: +300 SMS (from January)
└─ Total Available: 1300 SMS credits

Month 2 Usage:
├─ Used: 900 SMS
└─ Remaining: 400 SMS

↓ Next Renewal

Month 3 (March)
├─ Base Quota: 1000 SMS credits
├─ Carried Over: +400 SMS (from February)
└─ Total Available: 1400 SMS credits

​

When to Use Limit Recurring

​

✅ Perfect For:

1. Prepaid Credits
   • SMS credits
   • Phone call minutes
   • API credits
   • Any prepaid resource where unused amount has value
2. Accumulative Allowances
   • Monthly data allowances that accumulate
   • Storage quotas that build up
   • Feature credits that don’t expire
3. User-Friendly Models
   • When customers should keep what they paid for
   • When unused quota represents value to the user
   • When you want to improve customer satisfaction

​

❌ Not Suitable For:

• Time-sensitive quotas that should reset completely (use Limit Metered instead)
• Usage-based billing where you charge per unit (use Charge Metered instead)
• Monthly fresh starts where previous usage doesn’t matter

​

Comparison: Limit Metered vs Limit Recurring

​

Scenario: 1000 Units Per Month

​

Limit Metered (Hard Reset)

Month 1: 1000 units
- Used: 700
- Unused: 300 ❌ Lost at month end

Month 2: 1000 units (fresh start)
- User starts with exactly 1000 units

​

Limit Recurring (Soft Reset with Carryover)

Month 1: 1000 units
- Used: 700
- Unused: 300 ✅ Carries forward

Month 2: 1000 base + 300 carryover = 1300 units
- User starts with 1300 units

​

Quota Sources and Breakdown

​

1. Base Plan Limit

​

2. Automatic Carryover

• Previous period: 1300 total, used 800
• Carryover: +500 credits

​

3. Manual Adjustments

• Compensation for service outage: +200 credits
• Correction for billing error: -50 credits

​

Total Quota Calculation

Total Available = Base Plan + Carried Over + Manual Adjustments

Base Plan:           1,000 credits
Carried Over:        +  500 credits
Manual Adjustment:   +  200 credits
────────────────────────────────────
Total Available:     1,700 credits

​

Viewing Your Quota

​

User Dashboard

📞 SMS Credits
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
800 / 1,700 credits used

Quota Breakdown:
├─ Base Plan        1,000 credits
├─ Carried Over       500 credits  ⓘ
└─ Admin Adjustment   200 credits  ⓘ

Current Period: Jan 1 - Jan 31, 2025

​

Quota Detail View

Quota Detail - SMS Credits
════════════════════════════════════════════

Current Period (Jan 1 - 31, 2025)
Total Limit: 1,700 credits
Used: 800 credits
Remaining: 900 credits

════════════════════════════════════════════

🔹 Base Plan Limit
Gold Plan: 1,000 credits

🔄 Carried Over from Previous Period
└─ From December 2024
   Previous Limit: 1,300
   Previous Used: 800
   Carried Over: 500 credits
   Date: Jan 1, 2025

✏️ Manual Adjustments
└─ Compensation for service outage
   Amount: +200 credits
   Adjusted by: Support Team
   Date: Jan 5, 2025

​

Integration with Event API

​

Reporting Usage

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": "sms_credits",
    "externalUserId": "$YOUR_USER_ID",
    "externalEventId": "sms_20250105_001",
    "metricProperties": {}
  }'

​

Checking Quota

{
  "code": 0,
  "data": {
    "currentValue": 800,
    "totalLimit": 1700,
    "metricLimit": {
      "metricId": 123,
      "code": "sms_credits",
      "metricName": "SMS Credits",
      "type": 4,
      "totalLimit": 1700,
      "planLimits": [
        {
          "planId": 50,
          "metricLimit": 1000
        }
      ],
      "quotaAdjustments": [
        {
          "id": 2,
          "quotaAmount": 500,
          "quotaType": "carryover",
          "reason": "Carry over from period 1704067200",
          "previousPeriodLimit": 1300,
          "previousPeriodUsed": 800,
          "adjustmentTime": 0
        },
        {
          "id": 4,
          "quotaAmount": 200,
          "quotaType": "manual",
          "reason": "Compensation for service outage",
          "adjustmentTime": 1704441600
        }
      ]
    }
  }
}

​

When Limit is Reached

{
  "code": 51,
  "message": "metric limit reached, current used: 1700, limit: 1700",
  "data": {}
}

​

Limit Boundary Behavior

• Limit = 1700, Current Used = 1690, Event Value = 10 → ✅ Allowed (1690 + 10 = 1700 ≤ 1700)
• Limit = 1700, Current Used = 1690, Event Value = 11 → ❌ Rejected (1690 + 11 = 1701 > 1700)
• Limit = 1700, Current Used = 1700, Event Value = 0 → ✅ Allowed (1700 + 0 = 1700 ≤ 1700)
• Limit = 1700, Current Used = 1700, Event Value = 1 → ❌ Rejected (1700 + 1 = 1701 > 1700)

​

Plan Limit and Quota Requirements

​

Important: Plan Limit Must Be Configured

​

Behavior When Plan Limit is Deleted

1. Quota Adjustments Do Not Take Effect:
   • Even if you have carryover quota or manual adjustments, they will not be applied
   • The system requires a base Plan Limit for quota adjustments to work
2. All Events Are Rejected:
   • All event creation attempts will be rejected
   • Error message: "metric limit reached, current used: X, limit: 0"
   • limit: 0 indicates that no Plan Limit is configured

• Limit types (Limit Metered, Limit Recurring) require a limit binding to function correctly
• Quota adjustments are designed to modify the base Plan Limit, not replace it
• Without a Plan Limit, the system cannot determine the usage boundary

• 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

​

Quota Adjustment Rules

• Plan Limit: 1000 credits
• Quota adjustment: +500 credits
• Total Limit: 1500 credits ✅

• Quota adjustment: +500 credits
• Total Limit: 0 (Quota does not apply)
• Result: All events rejected ❌

​

Manual Quota Adjustments

​

Common Scenarios

1. Service Compensation
   • Service outage or downtime
   • Billing errors
   • Technical issues affecting usage
2. Customer Support
   • Goodwill gestures
   • Special promotions
   • Account corrections
3. Business Adjustments
   • Plan upgrades/downgrades
   • Credit transfers
   • Refund processing

​

How It Works

1. Administrator logs into the admin portal
2. Navigates to your user or subscription details
3. Opens the Metrics tab
4. Selects the Limit Recurring metric
5. Clicks “Adjust Quota”
6. Enters adjustment amount (positive to increase, negative to decrease)
7. Provides a reason (required)
8. Submits the adjustment

• Adjustments can be positive (increase) or negative (decrease)
• A reason is always required for audit purposes
• Adjustments take effect immediately
• All adjustments are logged with timestamp and operator

​

Plan Upgrade and Downgrade Scenarios

​

Normal Upgrade (Cross-Period Upgrade)

• ✅ Quota carryover: Unused quota from the previous period is automatically carried over
• ✅ Usage preservation: Previous period’s usage data is preserved
• ✅ Base quota: You receive the new plan’s base quota
• ✅ Total calculation: Total = New base quota + Carried over quota

Period 1 (January) - Plan A
├─ Base Quota: 1000 credits
├─ Used: 700 credits
└─ Remaining: 300 credits

↓ Normal Upgrade to Plan B (at period end)

Period 2 (February) - Plan B
├─ Base Quota: 2000 credits (from Plan B)
├─ Carried Over: +300 credits (from Period 1)
└─ Total Available: 2300 credits

• Upgrade happens at the end of a billing period
• Full quota carryover is applied
• All quota sources (plan limit, carryover, manual adjustments) are preserved

​

Proration Upgrade (Mid-Period Upgrade)

• ✅ Quota carryover with refund adjustment: Unused quota is normally carried over, but a refund adjustment is created to offset the plan limit portion (to avoid business loss since the old plan receives a refund)
• ❌ Usage does not carry over: Usage data is not carried over to the new period (usage starts from 0, consistent with normal renewal)
• ✅ Base quota: You receive the new plan’s base quota for the remaining period
• ✅ Manual adjustments preserved: Admin manual adjustments are carried over (protected user benefit)

Period 1 (January 1-31) - Plan A
├─ Base Quota: 1000 credits (from Plan A)
├─ Admin Adjustment: +200 credits
├─ Previous Carryover: +50 credits
├─ Total Limit: 1250 credits
├─ Used: 500 credits
└─ Remaining: 750 credits

↓ Proration Upgrade to Plan B (January 15)
   - Old plan refunded 50% of remaining period
   - Period End stays: January 31
   - Period Start updates: January 15

Period 1 (January 15-31) - Plan B
├─ Base Quota: 2000 credits (from Plan B, prorated)
├─ Carried Over: +750 credits (normal carryover: 1250 - 500)
├─ Refund Adjustment: -1000 credits (offsets Plan A's plan limit)
├─ Total Available: 2000 + 750 - 1000 = 1750 credits
└─ Usage: 0 credits (starts from 0, usage does not carry over)

• Normal carryover: All remaining quota (including plan limit, admin adjustments, and previous carryover) is carried over normally
• Refund adjustment: A negative refund adjustment (QuotaType: "proration_refund") is created to offset the plan limit portion
• Result: User benefits (carryover and manual adjustments) are preserved, while business loss is avoided (plan limit offset by refund adjustment)

• Protects user benefits: Carryover quota and admin manual adjustments are preserved
• Avoids business loss: Plan limit portion is offset by refund adjustment (since the old plan receives a refund)
• Fair and transparent: Clear logic with normal carryover + refund adjustment

• Usage does not carry over to the new period (consistent with normal renewal behavior)
• New period usage starts from 0
• Previous period’s usage data is preserved in historical records and can be queried via history API
• This is fair because the old plan was refunded and the user enjoys the new plan’s quota

• ❌ All aggregation types (Sum, Count, CountUnique, Latest, Max): Usage does not carry over
• ✅ New period usage starts from 0 for all aggregation types
• ✅ Consistent with normal renewal behavior

​

Downgrade Scenarios

• ✅ Quota carryover works the same as normal upgrade
• Unused quota is carried over to the new plan

• ✅ Quota carryover with refund adjustment (same as proration upgrade)
• ❌ Usage does not carry over (starts from 0, consistent with normal renewal)

​

One-Time Addon Behavior

• One-time addons are purchased separately and have their own billing period
• They provide additional quota for a specific metric

Period 1 - Plan A + One-Time Addon
├─ Plan A Limit: 1000 credits
├─ One-Time Addon: +500 credits
├─ Total: 1500 credits
├─ Used: 800 credits
└─ Remaining: 700 credits

↓ Normal Upgrade to Plan B

Period 2 - Plan B
├─ Plan B Limit: 2000 credits
├─ Carried Over: +700 credits (includes addon's remaining quota)
└─ Total: 2700 credits

Period 1 - Plan A + One-Time Addon
├─ Plan A Limit: 1000 credits
├─ One-Time Addon: +500 credits
├─ Total: 1500 credits
├─ Used: 800 credits
└─ Remaining: 700 credits

↓ Proration Upgrade to Plan B (mid-period)

Period 1 (remaining) - Plan B
├─ Plan B Limit: 2000 credits (prorated)
├─ Carried Over: +700 credits (normal carryover: 1500 - 800)
├─ Refund Adjustment: -1000 credits (offsets Plan A's plan limit)
├─ Total: 2000 + 700 - 1000 = 1700 credits
└─ Usage: 0 credits (starts from 0)
⚠️ Note: One-time addon's remaining quota is included in carryover, but plan limit portion is offset by refund adjustment

• One-time addons are attached to the purchase period
• In normal upgrades, addon quota is preserved through carryover
• In proration upgrades, all remaining quota (including addon quota) is carried over normally, but plan limit portion is offset by refund adjustment

​

Best Practices

​

For Business Owners

1. Choose the Right Type
   • Use Limit Recurring for prepaid credits
   • Use Limit Metered for monthly resets
2. Set Appropriate Limits
   • Consider how quota will accumulate over time
   • Plan for carryover amounts in your pricing model
3. Monitor Usage Patterns
   • Track how much quota carries over
   • Adjust base quotas if needed

​

For Developers

1. Check Quota Before Operations
   • Always verify quota availability before processing
   • Handle limit-exceeded errors gracefully
2. Handle Carryover Correctly
   • System automatically handles carryover
   • No manual intervention needed
3. Implement Proper Error Handling
   • Show clear messages when quota is exhausted
   • Provide quota breakdown information to users

​

Frequently Asked Questions

​

Q: What happens if I don’t use any quota in a month?

​

Q: Can quota accumulate indefinitely?

​

Q: What happens when I change plans?

• ✅ Your carryover quota is preserved
• ✅ You’ll receive the new plan’s base quota
• ✅ Total = New base quota + Existing carryover
• ✅ All quota sources (plan limit, carryover, manual adjustments) are carried over

• ✅ Quota carryover with refund adjustment: Unused quota is normally carried over, but a refund adjustment offsets the plan limit portion (to avoid business loss since the old plan receives a refund)
• ❌ Usage does not carry over: Usage data does not carry over to the new period (usage starts from 0, consistent with normal renewal)
• ✅ You’ll receive the new plan’s base quota for the remaining period
• ✅ Manual adjustments are carried over (protected user benefit)

• The metric becomes unavailable
• Historical quota is preserved but not usable

​

Q: Can I request a quota adjustment?

​

Q: How do I see my quota breakdown?

​

Q: What’s the difference between Limit Metered and Limit Recurring?

• Limit Metered: Quota resets completely each cycle (unused quota is lost)
• Limit Recurring: Unused quota carries over to the next cycle (unused quota is preserved)

​

Related Topics

• What is Billable Metric?
• Work with Limited-Type Metric
• Work with Charged-Type Metric
• Viewing User Usage Billing