Skip to content

Consumption and metering

This page explains what a consumption overlay is, what you configure in the SDKs to support one, and how the usage you record turns into money.

What a consumption overlay is

Section titled “What a consumption overlay is”

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"];
});
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',
  encodedCredential: process.env.MONAIQ_CREDENTIAL  // SIDUB_LIC_...
});

The Node client also takes billableResourceId, which names what the usage is billed against. Node client 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.

How usage is attributed

Section titled “How usage is attributed”

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.

Enforcing a rate limit

Section titled “Enforcing a rate limit”

In Node, RateLimitAssertion is the assertion for a rate-limited feature; the other assertions are in Node client 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.

Enforcing an allowance

Section titled “Enforcing an allowance”

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 (“Set an allowance” on the product’s features, then the allowance on compose).

The count lives on the platform. Every use your application records through the consumption service is folded into a per-period counter, and each authorization the server issues carries, for every allowance feature, the entitlement (Allowance), what the period had used when the authorization was issued (Used) and when the period ends (PeriodEndUtc). The SDK asserts against that stamp plus the uses it has recorded since.

In .NET: get the feature, record the use with QuotaLicenseFeatureOperation, then assert with QuotaLicenseAssertion.Create(featureKey). In Node: client.performOperation(...), then QuotaAssertion.create(featureKey). Both assertions pass at exactly the allowance and fail one use past it, the same boundary the rate limit uses.

Two things follow from where the count lives. Usage reported since the last authorization refresh is known to the runtime that reported it and to the platform, but not yet to other runtimes until they refresh. And the allowance is a soft ceiling by design: if the consumption pipeline is stopped, the count stops advancing and the allowance fails open rather than locking paying customers out.

A use the assertion refuses is not a use: the SDK neither counts nor reports it, and the platform records of any report only what the allowance still covers, so a runtime that could not yet see another runtime’s uses cannot push the count past the entitlement either. The period counter comes to rest at the allowance, and nothing past the entitlement reaches an invoice. Every use the seat does cover is recorded, so billing stays correct.

How usage becomes an invoice line

Section titled “How usage becomes an invoice line”

Usage accrues through the billing period and is billed for that period, on top of the base price the offering already charges. The invoice it lands on moves through Draft, Finalized and Paid as the period closes and payment is taken.

Both sides can see it:

Next

Section titled “Next”