Usage-Based license
A Usage-Based license (MeteredCount, metering mode Count) is
always online. Customers share one use counter across all devices on the
license key. Every consume deducts quantity from the remaining uses — there is no per-feature
token pricing (unlike Credit-Based).
Shared counter
One “uses” balance per license key.
Flat deduction
Each consume costs quantity (usually 1).
Usage tab
Balance, ledger, manual top-ups (owners).
Usage-Based license — for product owners
- Issue with initial use balance — no per-feature pricing required.
- Grant or adjust balance from the Usage tab or meter API (
POST /api/meter/grant,adjust). - Review ledger and run reconciliation to verify wallet vs entries.
- Entitlement sets restrict which feature names can be consumed.
- Always online — no offline Usage-Based mode.
Detailed wizard and API examples are documented below.
Usage-Based license — for end users
Your license includes a fixed number of uses shared across your team’s devices. The app remains licensed at zero uses, but metered actions stop with insufficient balance.
- Each billable action typically costs 1 use (integrator may pass higher quantity).
- When uses run out, ask your admin for a top-up or plan upgrade.
- View remaining uses in-app if the vendor exposed balance UI.
When to choose Usage-Based
Choose Usage-Based when you sell a fixed number of actions and every billable
operation should count the same — typically one use per call. The customer starts with a balance
(for example 500 uses). Each time they run a metered feature, your app calls ConsumeMeterAsync and the
server subtracts 1 use (or more if you pass a higher quantity).
Think of it like a punch card: “This license includes 500 exports.” Export #1 uses one punch, export #2 uses one punch — it does not matter which export template they pick; each export costs the same.
Good fits
- Simple bundled SKUs — “500 PDF exports per year” or “1,000 API calls included.”
- Evaluation limits — “Try 50 full runs before buying a larger pack.”
- Flat per-event billing — every report generated, every sync job, every upload counts as one use.
- Operations that should not need a price table — you do not want to maintain different credit costs per feature.
How it behaves in LicenPro
- Dashboard label: Usage-Based. API enum:
MeteredCount. - Balance is shown in uses (shared across all devices on the license key).
- No per-feature pricing — the feature name is for entitlement and audit; cost is always
quantity. - Example: customer has 500 uses → one consume with
quantity: 1leaves 499 uses, regardless of feature name.
When to use Credit-Based instead
If different features should burn the wallet at different rates — a light API call costs 1 credit
but a heavy AI job costs 50 — use Credit-Based (MeteredToken)
and configure a token price per feature.
At a glance
| Property | Value |
|---|---|
| Backend enum | LicenseType.MeteredCount (value 7) |
| Dashboard label | Usage-Based |
| Metering mode | MeteringMode.Count |
| Balance unit | uses |
| Cost per consume | quantity (1 use per unit by default) |
| Feature pricing | Not used — feature name is for entitlement/audit only |
| Activation mode | Online only |
| Seat limit | None — wallet/counter is the limit, not device seats |
Key invariant
Balance is only checked and deducted in POST /api/meter/consume.
Validation and activation succeed even at zero uses; your app must call consume when the
metered action runs and handle InsufficientBalance (HTTP 402).
Create a Usage-Based license (dashboard)
Open Licenses → Generate License. Four steps: Activation → License Type → Basic Info → Details.
Step 1 — Activation
Select Online. Usage-Based is always-online; offline mode hides metered type cards.
Step 2 — License type
Select the Usage-Based card (“One use per action”). Description: shared use counter, manual top-ups from the dashboard.
Step 3 — Basic info
- Product and Software release (required).
- Issued to — end user for the release.
- License name — internal label.
- Optional Entitlement set — restricts which feature names may be consumed.
Step 4 — Details
- Initial uses balance (
initialMeterBalance) — required, must be > 0 (e.g. 500 uses). - Notes — operator context.
Backend creates MeterWallet { mode: Count } and an InitialGrant ledger entry.
Create Usage-Based license, initial 500 uses
└─ MeterWallet { mode: Count, balance: 500 }
└─ UsageLedger { type: InitialGrant, amount: +500, balanceAfter: 500 }
No feature pricing step
Unlike Credit-Based, Usage-Based ignores FeatureMeterPricing.
ResolveCostAsync sets cost = quantity regardless of feature name.
Configure entitlements if you need to restrict which features can be metered.
Activation & sessions
- Always-online — same activation/session requirements as other online types.
- No activation seat cap — unlimited devices may activate the same key.
- Use global Activations / Sessions pages for cross-license support views.
Runtime — SDK & API
Every consume carries an operation id — the server's idempotency key. It is
required: a consume without one returns MissingOperationId and nothing is
charged. Create it with MeterManager.CreateOperationId, persist it before the
call, and re-send the same id for every retry of that one operation. A fresh id per attempt is
a second charge.
var client = new LicenseClient(options);
// 1. Validate (always online — validation never looks at the balance)
var result = await client.ValidateAsync();
if (!result.IsValid) return;
// 2. One operation id per logical operation, persisted BEFORE the call.
// On a restart, re-send the stored id — a new id would be a second charge.
var operationId = File.Exists(pendingOperationFile)
? File.ReadAllText(pendingOperationFile)
: MeterManager.CreateOperationId("ApiCall");
File.WriteAllText(pendingOperationFile, operationId);
// 3. Consume. Every attempt re-sends the SAME id, so a lost response is
// replayed by the server instead of charged again.
var consume = await client.ConsumeMeterWithRetryAsync("ApiCall", operationId, quantity: 1);
if (consume.Success)
{
// Settled. consume.IdempotentReplay tells you whether this call or an earlier
// attempt was the one that paid; consume.Balance is what is left.
File.Delete(pendingOperationFile);
}
else if (consume.IsInsufficientBalance)
{
// Nothing was charged. Top up, then start a new operation id.
File.Delete(pendingOperationFile);
}
else if (consume.IsRetryable)
{
// Keep the file: retry later with the SAME operation id.
}
else
{
// consume.Message is a sentence fit to show a user, never a raw error code.
}
// 4. Optional — remaining uses, without deducting
var balance = await client.GetBalanceAsync();
ConsumeMeterAsync and ConsumeMeterWithRetryAsync call
POST /api/meter/consume with the product X-API-KEY.
ConsumeMeterWithRetryAsync needs SDK 1.9.0 or newer; on older versions call
ConsumeMeterAsync in your own loop and pass the same operationId every time.
Retrying safely
A timed-out consume is the dangerous one: the server may have moved the balance and only the response
was lost. There is no separate “was I charged?” endpoint, and none is needed —
re-sending the same operation id is the probe. The server returns the original outcome
with IdempotentReplay = true and the balance does not move again.
| Outcome | Retry with the same operation id? |
|---|---|
IsNetworkError | Yes — the charge may or may not have landed; the replay settles it |
IsConcurrencyConflict | Yes — two calls raced on the wallet and this one lost |
IsIdempotencyConflict | Never — that id was already used for a different feature, quantity or device |
IsInsufficientBalance | No — nothing was charged. Top up, then start a new operation id |
IsRetryable | The one flag to branch on: true only for transient failures |
The device id is part of the server's idempotency fingerprint, so an id that changes between attempts
turns a safe replay into IdempotencyConflict. The SDK pins it once per process; call
MeterManager.SetHardwareId when your host supplies its own.
Read the balance without deducting: GET /api/meter/balance with the key in the
X-License-Key header (API key auth; the legacy ?licenseKey= query is still
accepted), or dashboard GET /api/meter/balance/{licenseId}.
Worked example
- Create license with initial 500 uses.
- Consume any entitled feature ×1 → balance 499.
- Consume ×600 in one call →
InsufficientBalance(402); balance unchanged at 499. - Consume ×499 → balance 0.
- Next consume ×1 →
InsufficientBalance(402). - Owner grants +1,000 → balance 1,000, ledger
AdminGrant.
Usage-Based, balance 100, consume quantity 3
└─ cost = 3 → balance 97
└─ UsageLedger { type: Consume, amount: -3, balanceAfter: 97 }
Usage tab (license detail)
Open a Usage-Based license → Usage tab.
| Role | What you see |
|---|---|
| Product owner / Admin | Remaining uses, grant form, full ledger (consumes + grants) |
| End user (My Licenses) | Read-only balance; consumption history where exposed |
| Member / Viewer | Read-only; no grant actions |
The balance card shows “Use mode — each consume deducts one use regardless of feature.” Grants require amount > 0 and are recorded as AdminGrant with optional reason and external reference (invoice / PO).
Analytics
GET /api/statistics/meter-usage aggregates both metered types:
meteredCountLicenseCount, total balance, period consumption, low-balance licenses, daily trend, and top licenses.
Consume error codes
Server codes, as MeterController returns them:
| ErrorCode | HTTP | Meaning |
|---|---|---|
InvalidRequest | 400 | Missing key, feature or operation id, or quantity <= 0 |
Unauthorized | 401 | Missing or invalid API key context |
LicenseNotFound | 404 | No license for the key |
NotMeteredLicense | 400 | Wrong license type |
LicenseInvalid | 400 | Status is not Valid (revoked, suspended) |
LicenseExpired | 403 | Calendar expiry passed — not covered by LicenseInvalid |
ProductAccessDenied | 403 | The API key user cannot access the license's product |
FeatureNotEntitled | 403 | Feature not in the entitlement sets (when sets are configured) |
InvalidActivation | 400 | activationId is not an active activation on this license |
ProductNotFound | 404 | The license has no resolvable product — inconsistent data, not a client error |
WalletNotFound | 404 | The license has no meter wallet |
InsufficientBalance | 402 | balance < cost — nothing was deducted |
IdempotencyConflict | 409 | The operation id was already used for a different operation. Never retry |
ConcurrencyConflict | 409 | Lost an optimistic-concurrency race. Retry with the same operation id |
InternalError | 500 | Unexpected server failure. Retry with the same operation id |
Usage-Based never returns PricingNotConfigured — that applies to Credit-Based only.
The SDK adds two codes of its own, without a server answer:
| ErrorCode | Raised by | Meaning |
|---|---|---|
MissingOperationId | SDK — no request sent | No operation id was supplied, so nothing was charged |
NetworkError | SDK — the request failed | The server could not be reached. The call may or may not have been charged — re-send the same operation id |
Usage-Based vs Credit-Based
Use this quick guide if you are deciding between the two metered types:
| Question | Usage-Based | Credit-Based |
|---|---|---|
| What are you selling? | A use counter (e.g. “500 exports”) | A credit wallet (e.g. “10,000 credits”) |
| Cost per action | Flat — 1 use per consume (unless you pass a higher quantity) | Variable — each feature has its own token cost |
| Setup before first consume | Create license with initial use count only | Set TokenCost per feature, then consume |
| Best analogy | Punch card — every action uses one punch | Prepaid wallet — different services cost different amounts |
