Skip to content

Consumption and metering

This page is for whoever makes your app bill customers by how much they use it. It explains what a consumption overlay is, what you configure in the SDKs to support one, and how the usage you record turns into money.

Every offering has one of two base pricing models: a subscription that recurs on a schedule, or a one-time purchase. Either can add a consumption overlay on top.

The overlay is two things together: features that are rate limited, and usage that is billed per period. There is no metered-only model on Monaiq, so consumption is always an addition to a base price rather than the whole of it. Sellers define the rate-limited features on the offering itself; Products and offerings covers that side.

Point the client at the consumption service

Section titled “Point the client at the consumption service”

Metered work runs against the consumption API rather than the licensing API, so the client needs both addresses.

In .NET, set both URIs on the options:

builder.Services.Configure<LicensingServiceOptions>(options =>
{
options.LicenseServiceUri = "https://api.monaiq.com/licensing";
options.ConsumptionServiceUri = "https://api.monaiq.com/consumption";
options.EncodedCredential = builder.Configuration["Licensing:EncodedCredential"];
options.IssuerClientId = Guid.Parse("<your account client id>");
options.ProductId = Guid.Parse("<your product id>");
});
builder.Services.AddSidubLicensing();

In Node, add consumptionServiceUri to the constructor:

const client = new LicensingClient({
licenseServiceUri: 'https://api.monaiq.com/licensing',
consumptionServiceUri: 'https://api.monaiq.com/consumption',
issuerClientId: '<your account client id>',
productId: '<your product id>',
encodedCredential: process.env.MONAIQ_CREDENTIAL // SIDUB_LIC_...
});

The JavaScript SDK also takes billableResourceId, which names what the usage is billed against. JavaScript SDK reference lists it.

Set ConsumptionServiceUri / consumptionServiceUri to the base address above. The SDK derives the rest: it reports to {consumptionServiceUri}/runtime/messages, presenting the credential’s runtime token as Authorization: Bearer. There is nothing extra to configure.

The .NET client buffers the uses you record and reports them on a timer. When the process stops, the SDK delivers what is buffered by itself: on a Microsoft.Extensions.Hosting 8.0 or later host (ASP.NET Core, the Functions isolated worker, a worker service) when the host stops, otherwise when the service provider is disposed. Nothing to wire. LicensingConsumptionBuffer.FlushAsync delivers everything buffered now, for the moments you want a report out early; .NET client reference shows the call and the buffer’s bounds. The JavaScript SDK reports each operation as it happens.

In Node, performOperation counts a use before it reports it. A rate limit and an allowance are enforced with no consumptionServiceUri set; the address decides only whether the use is reported.

Each flush names one seat, and the gateway checks the batch against the credential that sent it: a batch reporting a seat the credential does not carry is refused before it is ingested. The credential’s own id travels with the batch as well, which is what makes revocation immediate on this path: usage reported under a revoked credential is dropped at ingestion rather than billed. Enforcement is the slower half: a revoked credential keeps authorizing until the application’s next authorization refresh. Credentials and keys states both timings.

In Node, RateLimitAssertion is the assertion for a rate-limited feature; the other assertions are in JavaScript SDK reference.

In .NET, the members involved are PerformOperation<TFeature, TState> for work that runs against a feature and AssertLicense for enforcing a condition, both on ILicensingService. See .NET client reference.

An allowance is the other way to bound a capability: so many uses per billing period, counted across every device and server the seat runs on. A rate limit caps how fast one runtime may use something; an allowance caps how much the whole seat may use before the period resets. Every seat of a license is entitled to the same allowance number, and counts its own uses against it. Sellers set the number on the offering (New feature on the product’s features, answering “Set an allowance”, then the allowance on compose).

An allowance of 0 has no cap: every use is counted and reported, and none is refused. The SDK spends it without a grant, and the seat’s figures read Used with nothing to count down (Remaining is 0, and the seller’s seat read says Uncapped).

A Limit is never counted by Monaiq. Your application holds the number (Limit, null for unlimited), asserts the count it would hold after an action, and reports nothing for it.

Record each use where the work happens. In .NET: get the feature with GetLicenseFeature<QuotaLicenseFeature>, then call PerformOperation with a QuotaLicenseFeatureOperation. In Node: client.performOperation(...).

A use the allowance does not cover is refused. The call throws AllowanceExhaustedException in .NET and AllowanceExhaustedError in Node, and the use is neither counted nor reported. Both carry the feature key, the allowance and PeriodEndUtc / periodEndUtc, when the period resets. Catch it, refuse the work, and name that date in the message you show. Never catch it and carry on.

The use that takes the last of the allowance passes. An allowance of zero or less is no cap and refuses nothing.

To refuse work before doing it, check first: await licensing.AssertAllowance(serviceRef, context, featureKey) in .NET, await client.assertAllowance(featureKey) in Node. The check returns true when the use fits, throws the same exception when it does not, and returns false when the license does not carry the allowance. It records nothing: do the work, then record the use.

Work that records several uses passes how many to both the check and the record. In .NET, QuotaLicenseAssertion.Covers(featureKey) is the same check as an assertion for AssertLicense.

QuotaLicenseAssertion.Create(featureKey) in .NET and QuotaAssertion.create(featureKey) in Node assert the last use: true, or the exception from a refused use until a use is covered again. Both return false for a feature the license does not carry, and ask the platform nothing.

An allowance fails closed:

  • The period cannot cover the use. It has nothing left, or less than the work records. The use is refused and the exception is thrown. After a refusal the SDK does not ask the platform again for up to a minute.
  • The platform cannot be reached. When the SDK needs the platform and cannot reach it, PerformOperation throws LicenseAuthorizationUnavailableException in .NET, and performOperation throws LicensingError in Node. The SDK does not try again for 30 seconds.

A refused use is not a use: the SDK neither counts nor reports it. The platform records of any report only what the allowance still covers, so nothing past the entitlement reaches an invoice. Every use the seat does cover is recorded, so billing stays correct.

ILicenseStateProvider.GetState in .NET and client.getState() in Node carry one entry for each allowance feature, with the seat’s figures for the current billing period:

.NET AllowanceView Node allowances[] Meaning
Allowance allowance The uses per billing period. Zero is no cap.
Used used The uses recorded in the period, on every runtime of the seat.
Reserved reserved Units the seat’s other runtimes hold and have not used yet.
Remaining remaining What this runtime can still use: Allowance less Used and Reserved, never below zero.
PeriodEndUtc periodEndUtc When the period resets.
AsOfUtc asOfUtc When the platform gave the figures.

The figures are the platform’s. Reading the state reads them from the platform when the runtime holds none for the period, or holds figures more than a minute old. The read uses none of the allowance, so a runtime that has made no use, has sat idle, or has just restarted shows the same figures as one that is busy.

  • This runtime’s uses are in Used and Remaining at once, with no call.
  • Other runtimes’ uses appear on the next read, so they are at most a minute late. Recorded uses also trail a use by the few seconds reporting takes.
  • Reserved returns to Remaining when a runtime stops or hands its units back.
  • After a refusal because the period is spent, Remaining is 0, and the next state read asks the platform again. Units another runtime has returned since then show without a use on this one.

Show the figures as unknown while PeriodEndUtc is null: the platform could not be reached and the runtime held none. Used is then 0 and Remaining the whole allowance. A read that fails never refuses a use and is not thrown; the SDK keeps the figures it has and reads again after 30 seconds.

The figures are for display. A use is always checked against the platform’s own count, whatever the figures say.

To report seats your application holds no runtime for, read them from your backend: GET /licensing-mgmt/licenses/{licenseId}/seats carries the same figures for every seat of a license.

When the process stops, the SDK settles with the platform by itself: what it did not use goes back to the seat, and the seat’s other runtimes can use it at once.

  • .NET. Nothing to wire or call. Under a generic host (ASP.NET Core, the Azure Functions isolated worker, a worker service) it happens when the host stops, after requests have drained. With no host it happens when the service provider is disposed, and on process exit.
  • Browser. Automatic, on pagehide.
  • React. Automatic: LicensingProvider does it when it unmounts.
  • Node. Automatic when the process ends on its own, including a process whose signal handler closes its servers and lets the event loop drain. Only code that calls process.exit() awaits client.disposeAsync() first.

Units a killed process never returns come back to the seat once they expire, an hour after the runtime took them, plus at most ten minutes.

A host that runs many instances of one process (a serverless or autoscaled plan) runs one runtime per instance, and every instance of a busy seat holds units of its own:

  • What an instance holds. One grant is a tenth of what the seat has not handed out, and an instance takes the next grant before the last runs out, so it holds up to two at once. Four busy instances of a seat with an allowance of 100 hold about half of it between them. Those units show as Reserved and are not lost: each instance spends them.
  • When an instance stops. A graceful stop returns its units at once (see above). A platform that kills instances on scale-in, a crash or a timeout leaves its units with the instance until they expire, up to about an hour. Until then the seat’s other runtimes cannot spend them.
  • Sizing. The share held depends on how many instances serve the seat at once, not on the size of the allowance: up to about a fifth for one instance, a third for two, and over half for four. A small allowance fares worse, because every grant is at least one unit. If a burst across many instances is followed by a scale-in, the seat can be refused with much of its period unspent until those units expire. Routing one seat’s work to few instances, and giving the host a graceful shutdown window, keeps more of the allowance usable.

Usage accrues through the billing period and is billed for that period, on top of the base price the offering already charges. Usage against a feature the license sets no per-unit rate for is still recorded, at zero: the use is on record and adds nothing to the invoice. The invoice it lands on is finalized and sent when the period closes, and is Paid once payment is taken.

Both sides can see it: