Metering, quotas & credits

Metering is how you count what a customer consumes, enforce limits, and — for usage-based plans — price that consumption against prepaid credit.

Counting: monitored assets

A monitored asset is one meter: the name usage is reported under, how it accumulates, and optionally its limits. Everything a product meters lives in the one list on its Metering & monitoring tab.

The asset’s type sets how readings accumulate, stated as what the application reports:

Type	The application reports
Incremental (`CumulativeCounter`)	each delta — 10, then 10 again, means 20
Running total (`TotalCounter`)	the cumulative figure — 10, then 20, means 20. Reset-aware
Gauge	the current value — 10, then 20, means 20
Up/down (`UpDownCounter`)	signed changes

Getting this wrong is a billing error, not a display one: report running totals against an incremental meter and 10, 20, 30 accumulates as 10, 30, 60, so quota limits are crossed too early. The technical names are counterintuitive, so the portal labels them by what the application reports.

You do not create meters by hand. A Metered feature gets one when you save it — named after the feature code, typed from the aggregation you declared on the feature, so the two can never disagree. The meter appears in the list with no quota and no balance until you add them.

A catalog entry alone is a definition, not something this version offers. The New feature dialog closes that gap in the same click: Add to this version is on by default, so the feature is defined and offered at once. Turn it off to define a feature a later version will pick up, and add it from Features in this version when it does.

Several features, one meter

Features to meters are n:1 — several features may report into one accumulator. To share a meter, choose an existing one when creating the feature; only meters that accumulate the same way are offered, because two features reporting into one accumulator must agree on how it accumulates.

When you create the feature, the metric name is prefilled and editable. Two reasons it is yours to set: a feature code is permanent and may not be a legal metric name, and several features can legitimately meter into one asset. Whatever you save is written onto the feature’s catalog entry at the same moment, so the feature and its asset always agree on the name that joins them — and naming an asset that already exists links this feature to it rather than making a second meter for the same thing. Once a feature has a metric name, changing it belongs on Feature catalog, where the rest of its definition is authored.

Capping: quota tiers

Consumption is measured per period (minute / hour / day / week / month / year) against quota tiers. Leave the period empty for an allowance that is spent once and never resets; any other word is rejected, rather than quietly behaving like that.

Resets decides where each window starts, separately from how long it is:

At the calendar boundary (the default) — an hourly window rolls at the top of the next clock hour in UTC. A first report at 10:47 gets thirteen minutes.
One period after first use — the window starts at the report that opens it, so an hourly quota gives a full hour from that moment. Each customer’s clock runs on their own first use, which is what “N per hour of use” usually means.

Either way the window is fixed and has one boundary: consuming more inside it does not extend it. Changing this on a live meter restarts the current window immediately, for every customer already on it.

Each tier carries a quota level — None, Normal, Warning, Critical, OverUsage — and an enforcement policy for when it’s crossed. Only two policies block on the server; the rest are signals returned to your application:

Policy	Kind	What happens
`None`	signal	No enforcement
`NotifyOnly`	signal	Allowed; the status tells you to notify
`AllowWithOverage`	signal	Allowed past the limit; the overage is tracked, and charged to a credit balance when the tier names one
`AllowWithGrace`	signal	Allowed; your app honours the grace allowance
`RateLimit`	signal	Allowed; your app does the throttling
`Deny`	blocking	The commit is refused, status in the response body
`SuspendUsage`	blocking	The commit is refused; usage on the asset is suspended

For the signal policies the server records the usage and hands the status back — it does not throttle or track grace itself. At two levels the server adjusts the configured policy: at moderate levels a harsher policy is softened (Deny at Warning acts as NotifyOnly), and at OverUsage a configured None escalates to Deny.

The tiers come from the plan in effect for the customer’s entitlement.

Pricing: credits & balances

Separately from raw counters, a credit balance is a prepaid account — a starting amount in a currency and unit you choose (credits, tokens…), drawn down as usage is consumed. Quota tiers can price that consumption (a base cost plus a per-unit rate), so metered use turns into credits spent — the basis for prepaid and usage-based pricing. Balances allow overage when you permit it, and can be topped up, withdrawn from, or suspended.

Paying for the overage

An AllowWithOverage tier can name the credit balance that funds it, together with what a unit costs there. The server then prices only the part of each call that lands past the tier’s start, and draws that from the balance before the meter moves:

A six-second video render at 25 of 30 included seconds is one second of overage, so it costs one credit — and it still runs with three credits in the pool.
If the balance cannot cover it, the commit is refused and neither the meter nor the balance moves. The refusal comes back the way every metered refusal does — a Deny status in the response body — with a reason (NoCredit, SpendingDisabled, BalanceExpired, BalanceSuspended) so you can tell “out of credits” from “over the plan limit”, and the price so you can say how much is missing.
A commit that goes through reports creditsCharged and fundedUnits, so your app can tell someone “five seconds included, one credit from your balance” without working the arithmetic out itself.

Usage that arrives late is priced the same way. An application that keeps metering while it is offline uploads its readings when it reconnects, and those readings pass through the same tiers and draw on the same balance — what a call costs does not depend on when it arrived. The one thing an upload cannot do is be refused: the work already happened, so the meter moves either way, what the balance can cover is charged, and anything left over stands as overage nobody has paid for yet.

An overage tier that names no balance keeps the plain signal behaviour: allowed past the limit, recorded, and left to your app.

Oclavex does the credit accounting — how much value a customer has bought and used — and hands charging to your billing provider (e.g. Stripe), feeding it the usage, overage and lifecycle signals through webhooks so it can issue the invoice or capture the payment.

How it relates

Counts → consumption reported by a session.
Capped by → the plan’s tiers.
Priced into → credits, feeding your billing.