Quota Management

Quota management is exclusive to Quota Subscription mode (subscription_quota). If you're using other modes, you can skip this page.

What Is Quota

After subscribing, users receive a fixed number of uses (quota) per month. For example, Pro users get 500 uses per month — once used up, they need to purchase extra credit packs.

Quota Configuration

Set in SUBSCRIPTION_PLANS in config/payment.ts:

pro: {
  priceMonthly: 29.99,
  priceYearly: 299.99,
  name: 'Pro',
  quota: 500,          // Monthly subscribers get 500 uses/month
  quotaYearly: 750,    // Yearly subscribers get 750 uses/month
  // ...
}

Yearly subscribers can have a higher monthly quota as a perk (quotaYearly). If not set, it defaults to the same as monthly.

Quota Reset Mechanism

Quotas reset monthly, but the reset logic differs between monthly and yearly subscribers:

Monthly Subscribers

Quota resets each time a renewal payment succeeds (when the renewal Webhook is received). No advance allocation — quota only resets after payment is confirmed.

Uses a lazy reset mechanism: each time the user accesses the service, the system checks whether the reset date has passed. If so, it automatically resets the quota and advances the reset date to the next month.

This design exists because yearly subscribers have paid for the entire year upfront, but quota is allocated monthly — no need to wait for a Webhook.

What Happens When Quota Runs Out

When quota is exhausted, the system automatically falls back to the user's credit balance (bonus credits → purchased credits). When everything is used up, access is denied. See Credits & Consumption for details.

Displaying Quota Info on the Frontend

Get quota information via the useAccess Hook:

import { useAccess } from '@/hooks/useAccess'

function QuotaDisplay() {
  const { status } = useAccess()
  const { quota } = status.details

  if (!quota) return null

  return (
    <div>
      <p>Monthly quota: {quota.monthlyLimit}</p>
      <p>Used: {quota.used}</p>
      <p>Remaining: {quota.remaining}</p>
      <p>Next reset: {new Date(quota.resetDate).toLocaleDateString()}</p>
    </div>
  )
}

Quota Changes on Plan Upgrades/Downgrades

Upgrade (takes effect immediately): Quota resets to the new plan, used amount cleared to zero
Downgrade (takes effect next cycle): Current cycle retains the original quota, next cycle switches to the new plan's quota