Skip to main content
A usage limit is the amount of a Meter feature a plan includes, such as 10,000 API calls a month. Your app reports usage, Kelviq counts it against the limit, and your app checks what’s left before letting the customer use more. This page follows one example: the Pro plan of an AI app costs $29 a month and includes 10,000 api-calls, reset monthly.

​
The terms

​
How usage is counted

Your backend reports usage for a customer and a Meter feature:
  • DELTA adds to current usage. Send it each time something is used: one API call, 1,200 tokens.
  • SET replaces current usage. Use it for numbers you already track, such as seats in use.
In the example, after 6,500 calls the customer’s entitlement looks like this:
See Features & limits for the SDK calls.

​
When usage resets

Each Meter feature on a plan has a usage reset: never, or a recurring period such as every day, month, quarter, or year. For monthly resets you choose the first day of the month or the customer’s subscription start date. A reset of Never makes the limit a lifetime allowance. Credit packs work this way.

​
What happens at the limit

For a Meter feature, hasAccess is true while remaining is above 0 or the limit is unlimited.
  • Hard limit: at 10,000 calls, hasAccess turns false and additional usage is stopped until the next reset or an upgrade.
  • Soft limit: usage keeps counting past 10,000. hasAccess is also false here, so check hardLimit before blocking. If the plan has an overage price, let the customer continue and the extra usage is billed.
Use usage alerts to warn customers before they get there, for example at 80% and 90%.

​
Overage

To charge for usage past the included amount, add a Pay as you go usage price to the plan, for example a Tiered price whose first 10,000 calls are free and each call after that costs $0.002. Kelviq bills the overage at the end of each monthly period from the usage you report. See Pay as you go.

​
Rollover

With an Advance commitment price, part of the unused allowance can carry into the next period. In the example, with 50% rollover capped at 750, a customer who has 2,000 calls left at the reset starts the next month with 10,750. See credit rollover.

​
Plan changes

When a customer upgrades or downgrades, the new plan’s limits apply immediately and current usage is kept. A customer who used 6,500 calls and downgrades to a plan with 5,000 is over the limit straight away.

​
Change one customer’s limit

From the customer’s page in the dashboard, you can override a limit for that customer or reset their usage to 0. Plan limits don’t change. See Managing customer entitlements.

​
If Kelviq can’t be reached

The Node and Python SDKs return the last known entitlement when the API is unreachable, and queue usage reports to retry later. See When the Entitlement API is unavailable.