Range Limits

Range limits let a SaaS product route usage from a subject, such as a user or API key, to a real billing account while tracking periodic limits for that subject.

Use this overview for the model and flow. For request and response details, open the individual endpoint pages.

Core Concepts

Concept	API or field	Description
Tenant	tenant_id	Top-level customer or workspace boundary.
Project	project_id	Isolation boundary for accounts, wallets, routes, usage, limits, ledgers, and voucher grants.
Billing account	Account / billing_account_id	The real billing entity inside a project, such as a SaaS customer, organization, team, or workspace.
Wallet	Wallet	Project-scoped currency balance, available balance, and credit limit under an account.
Usage subject	subject_type + subject_id	Entity that produces usage, for example user/user_123, api_key/key_001, or workspace/ws_001.
Usage control rule	UsageControlRule	Route that maps a usage subject to a billing account and optional limits.
Range limit	limits[]	Periodic accumulation limit, for example one million tokens per user per week.
Metric scope	metric_scope	Limit accumulation scope. amount accumulates money; other values accumulate matching charge item metrics or units.

Integration Flow

1. Open the project that owns the usage and billing state.
2. Create an account for the real billing entity in that project.
3. Create a wallet for the account and currency.
4. Optionally credit the wallet.
5. Create a usage control rule for each usage subject that should bill to the account.
6. Configure limits[] on the rule when that subject needs daily, weekly, or monthly limits.
7. Query realtime usage limits to read limit windows and usage; query realtime wallet amount separately when you need funds.

Manual Resets

Use Reset Usage Limits when a customer needs a quota reset outside its calendar window. Resets can apply to a whole project, one billing account, one Usage Limit Plan population, or one subject route. They are event-time boundaries: a late report for usage that occurred before the reset remains historical and is not counted into the new limit generation.

Organization Billing with User Limits

For a SaaS organization with multiple users, the recommended model is:

• create one account and wallet for the organization;
• create one usage control rule per user;
• set every user rule’s billing_account_id to the same organization account;
• set each rule’s subject_type and subject_id to that specific user;
• configure that user’s own limits on the rule.

When user_123 reports usage in the project, the organization wallet in that same project is debited, but only user_123’s limit window is incremented. Usage from user_456 debits the same wallet but increments user_456’s separate limit window.

Period Windows

period	Window example	Description
hour / 1h	2026-06-29 14:05:12	Anchored hour window.
day / daily	2026-06-29	Calendar day.
week / weekly	2026-W27	ISO week.
month / monthly / 1 month	2026-06-29 10:23	Anchored window from the usage-limit anchor.

Day, week, and month windows are calculated in local time after applying timezone. If timezone is not configured, UTC is used. All anchored windows start from the subject route’s usage-limit anchor, so a route enabled at 10:23 with period=month resets next at 10:23 one month later, and custom windows such as 7d, 5h, 5 day, 2 week, or 5 month keep advancing from that same anchor.

Metric Scope

metric_scope	Accumulation	Common use
amount	Sum same-currency ChargeItem.Amount values.	Daily or monthly spend caps.
tokens	Sum quantity for charge items whose metric or unit matches tokens.	Weekly token caps.
requests	Sum quantity for charge items whose metric or unit matches requests.	Daily request caps.
Custom value	Sum quantity for a matching metric or unit.	Tool calls, task minutes, workflow runs, or data processed.

Non-amount scopes use charge item quantity. During usage processing, Meterry considers both the charge item’s metric and unit as possible scopes.

Usage Event Requirements

Range limit and realtime wallet behavior depends on rated charge items. Make sure:

1. The usage event is processed by a published extractor rule set in the same project as the account route.
2. The event subject matches the subject_type and subject_id in the usage control rule.
3. Charge items include currency and a computed amount for wallet deduction.
4. Non-money limits use a metric_scope that matches a charge item metric or unit.

In organization-billed, user-limited flows, extract the subject as the user, for example subject_type=user and subject_id=user_123. Keep organization ID as a dimension or metadata field, not as the usage subject.