Concepts
Single page glossary.
Every term used across the Limitr docs is defined here. Reference pages link back rather than re-explaining vocabulary.
Policy
A versioned document that defines your entire pricing model. Written in YAML, JSON, TOML, or Stof. Loaded into your application at runtime via Limitr.new() (local) or Limitr.cloud() (managed).
The policy is the source of truth for enforcement, metering, and margin. Nothing about pricing lives in your application code.
Credit
The unit of measure for something your product delivers. Every entitlement limit is denominated in a credit; every meter tracks consumption in a credit.
Discrete credit — A credit tied to a specific resource with real cost attached: an AI input token, a GPU second, a megabyte of storage. Has overhead_cost (what it costs you) and price (what you charge), which makes per-customer margin tracking possible.
Abstract credit — A credit representing a conceptual unit your business or customers understand: "AI Credits", "messages", "reports". Has no cost attached directly. Maps to discrete credits through the exchange table. Useful when you want customers to buy a bundle without exposing per-token or per-MB pricing.
Exchange
A table in the policy that defines how credits convert into one another. All values are expressed relative to the rune — Limitr's internal base currency, where 1 rune = 1 USD by default.
The exchange table is what allows a pool of abstract credits to drain across multiple discrete entitlements, and what enables margin calculation across any combination of resources.
Rune — Limitr's internal currency unit. The exchange table anchors every credit to a rune value, enabling conversion between any two credits with a defined chain.
Grant strategy — The rule that governs which grant is consumed first when multiple grants are eligible. Options: expires_first (default), cheapest_first, valuable_first.
Plan
A named tier bundling entitlements for customers — free, starter, growth, enterprise, or whatever your product defines. Plans specify which credits customers on that tier can consume, at what limits, and which topups are available or included automatically.
Every customer is on exactly one plan at a time.
Entitlement
A specific resource a customer on a plan is allowed to use. Entitlements live inside plans and are identified by name (chat_input, seats, pdf_export).
- Without a limit — acts as a boolean flag. Present means allowed; absent means denied.
- With a limit — metered. Consumption is tracked and enforced against the limit.
Limit
The constraint on an entitlement. Defines the credit being metered, the maximum value, and how enforcement behaves when the limit is reached.
| Mode | Behavior |
|---|---|
hard | Blocks at the limit. No overage allowed (except when covered by a grant). Fires meter-limit events. |
soft | Allows consumption past the limit. Fires meter-overage events your code or Cloud can route to billing. |
observe | No enforcement. Meters indefinitely. Useful for visibility without blocking. |
Limits can reset on a schedule (resets: true, reset_inc: 1day). They can also be overridden per-customer without changing the plan.
Customer
Any entity that consumes entitlements — a user, an organization, a workspace, a seat. Customers are identified by a primary ID, can carry alternative IDs (e.g. a Stripe customer ID), and can reference other customers (e.g. an org referencing its members).
Each customer carries their own meters, overrides, and grants.
Meter
The per-customer, per-entitlement consumption counter. Updated automatically on every allow(), increment(), or decrement() call. Stores the credit ID and the current value in that credit's units.
Meters reset when their entitlement limit's reset schedule fires.
Topup
A credit package that can be applied to a customer — purchased explicitly or included automatically in a plan. When applied, a topup creates a grant on the customer.
Topups can carry a price, reset on a schedule, support rollover, and expire after a configurable period.
Grant
A credit balance on a specific customer, created when a topup is applied. When a soft-limit entitlement goes into overage, Limitr draws from the customer's eligible grants before firing a meter-overage event.
Grants track their starting_value, current value, reset behavior, expiry, and which topup created them.
Notification
A policy-defined rule that fires when a specific event condition is met. Written in Stof. Defines a matches(type, event) function to filter events, and a fire function to handle them.
In Limitr Cloud, notifications route automatically to Slack, email, or webhook. Locally, they fire in-process and are handled via addHandler().
Capability
A named, callable unit of policy logic with defined input/output parameters. Used to expose policy-aware functions as tool definitions — for example, as Claude MCP tool definitions in an agent pipeline.
Capabilities are a Cloud and Limitr Network concept. They're not required for local enforcement.