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:

Prepaid Credits
- SMS credits
- Phone call minutes
- API credits
- Any prepaid resource where unused amount has value
Accumulative Allowances
- Monthly data allowances that accumulate
- Storage quotas that build up
- Feature credits that don’t expire
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": {}
}

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 = 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

Limit Recurring metrics require a Plan Limit to be configured. Quota adjustments (carryover and manual adjustments) only take effect when a Plan Limit exists.

Behavior When Plan Limit is Deleted

If the Plan Limit is deleted or not configured:

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

Why this behavior?

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

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

Quota Adjustment Rules

Quota adjustments only work when Plan Limit exists:

Scenario	Plan Limit	Quota	Behavior
Normal operation	✅ Exists	✅ Exists	✅ Quota is added to Plan Limit
Plan Limit deleted	❌ Deleted	✅ Exists	❌ Quota does not take effect, all events rejected
No Plan Limit	❌ Not configured	✅ Exists	❌ Quota does not take effect, all events rejected

Example:

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

If Plan Limit is deleted:

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

Manual Quota Adjustments

Administrators can manually adjust your quota for various reasons:

Common Scenarios

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

How It Works

Administrator logs into the admin portal
Navigates to your user or subscription details
Opens the Metrics tab
Selects the Limit Recurring metric
Clicks “Adjust Quota”
Enters adjustment amount (positive to increase, negative to decrease)
Provides a reason (required)
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

Plan Upgrade and Downgrade Scenarios

When you upgrade or downgrade your subscription plan, the system handles quota carryover differently depending on the type of upgrade.

Normal Upgrade (Cross-Period Upgrade)

What happens:

✅ 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

Example:

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

Key points:

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)

What happens:

✅ 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)

Example:

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)

How it works:

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)

Why this approach?

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 handling:

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:

❌ 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

Normal downgrade (at period end):

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

Proration downgrade (mid-period):

✅ 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

What are One-Time Addons?

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

Normal upgrade with one-time addon:

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

Proration upgrade with one-time addon:

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

Important notes:

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

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

For Developers

Check Quota Before Operations
- Always verify quota availability before processing
- Handle limit-exceeded errors gracefully
Handle Carryover Correctly
- System automatically handles carryover
- No manual intervention needed
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: The behavior depends on the type of plan change: Normal upgrade/downgrade (at period end):

✅ 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

Proration upgrade/downgrade (mid-period):

✅ 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)

If the new plan doesn’t include the metric:

The metric becomes unavailable
Historical quota is preserved but not usable

For detailed examples, see the Plan Upgrade and Downgrade Scenarios section above.

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?

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)

​Work with Limit Recurring Metric

​Overview

​Key Features

​How It Works

​Basic Concept

​Example: Monthly SMS Credits

​When to Use Limit Recurring

​✅ Perfect For:

​❌ Not Suitable For:

​Comparison: Limit Metered vs Limit Recurring

​Scenario: 1000 Units Per Month

​Limit Metered (Hard Reset)

​Limit Recurring (Soft Reset with Carryover)

​Quota Sources and Breakdown

​1. Base Plan Limit

​2. Automatic Carryover

​3. Manual Adjustments

​Total Quota Calculation

​Viewing Your Quota

​User Dashboard

​Quota Detail View

​Integration with Event API

​Reporting Usage

​Checking Quota

​When Limit is Reached

​Limit Boundary Behavior

​Plan Limit and Quota Requirements

​Important: Plan Limit Must Be Configured

​Behavior When Plan Limit is Deleted

​Quota Adjustment Rules

​Manual Quota Adjustments

​Common Scenarios

​How It Works

​Plan Upgrade and Downgrade Scenarios

​Normal Upgrade (Cross-Period Upgrade)

​Proration Upgrade (Mid-Period Upgrade)

​Downgrade Scenarios

​One-Time Addon Behavior

​Best Practices

​For Business Owners

​For Developers

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

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

​Related Topics

Work with Limit Recurring Metric

Overview

Key Features

How It Works

Basic Concept

Example: Monthly SMS Credits

When to Use Limit Recurring

✅ Perfect For:

❌ Not Suitable For:

Comparison: Limit Metered vs Limit Recurring

Scenario: 1000 Units Per Month

Limit Metered (Hard Reset)

Limit Recurring (Soft Reset with Carryover)

Quota Sources and Breakdown

1. Base Plan Limit

2. Automatic Carryover

3. Manual Adjustments

Total Quota Calculation

Viewing Your Quota

User Dashboard

Quota Detail View

Integration with Event API

Reporting Usage

Checking Quota

When Limit is Reached

Limit Boundary Behavior

Plan Limit and Quota Requirements

Important: Plan Limit Must Be Configured

Behavior When Plan Limit is Deleted

Quota Adjustment Rules

Manual Quota Adjustments

Common Scenarios

How It Works

Plan Upgrade and Downgrade Scenarios

Normal Upgrade (Cross-Period Upgrade)

Proration Upgrade (Mid-Period Upgrade)

Downgrade Scenarios

One-Time Addon Behavior

Best Practices

For Business Owners

For Developers

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?

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?

Related Topics