Skip to main content

​
Work with Limit Recurring Metric

​
Overview

Limit Recurring is a metric type designed for prepaid credits and allowances where unused quota has value and should be preserved across billing cycles. Unlike Limit Metered which resets completely each month, Limit Recurring automatically carries over unused quota to the next billing period.

​
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

Limit Recurring uses a “soft reset” approach:
  • 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
Best for: Monthly allowances where unused quota doesn’t matter (e.g., API rate limits)

​
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
Best for: Prepaid credits where unused amount has value (e.g., SMS credits)

​
Quota Sources and Breakdown

Your total available quota comes from three sources:

​
1. Base Plan Limit

The quota amount defined in your subscription plan for the current billing period. Example: Gold Plan includes 1000 SMS credits per month

​
2. Automatic Carryover

Unused quota from the previous billing period, automatically calculated and transferred. Example:
  • Previous period: 1300 total, used 800
  • Carryover: +500 credits

​
3. Manual Adjustments

Administrator adjustments for compensation, corrections, or special cases. Example:
  • Compensation for service outage: +200 credits
  • Correction for billing error: -50 credits

​
Total Quota Calculation

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

​
Viewing Your Quota

​
User Dashboard

When viewing your usage, you’ll see: 
📞 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

Click on the info icon (ⓘ) to see detailed information: 
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

You report usage the same way as other metric types using the Event API: 
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

The API response includes your current usage and total available 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

If you exceed your quota limit, the API will return an error: 
{
  "code": 51,
  "message": "metric limit reached, current used: 1700, limit: 1700",
  "data": {}
}

​
Manual Quota Adjustments

Administrators can manually adjust your quota for various reasons:

​
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
Adjustment Rules:
  • 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

​
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?

A: Your full base quota (e.g., 1000 credits) will carry over to the next month. You’ll start the next period with your base quota plus all unused quota.

​
Q: Can quota accumulate indefinitely?

A: Yes, there’s no upper limit by design. If your business needs a cap, it would require additional configuration.

​
Q: What happens when I change plans?

A: If the new plan includes the same metric:
  • Your carryover quota is preserved
  • You’ll receive the new plan’s base quota
  • Total = New base quota + Existing carryover
If the new plan doesn’t include the metric:
  • The metric becomes unavailable
  • Historical quota is preserved but not usable

​
Q: Can I request a quota adjustment?

A: Yes, contact customer support if you believe you’re entitled to a quota adjustment (e.g., service issues, billing errors).

​
Q: How do I see my quota breakdown?

A: View it in your user dashboard or through the API. The breakdown shows base plan, carryover, and manual adjustments separately.

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

A:
  • 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)