LicenPro
DocumentationUsage-Based

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: 1 leaves 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

PropertyValue
Backend enumLicenseType.MeteredCount (value 7)
Dashboard labelUsage-Based
Metering modeMeteringMode.Count
Balance unituses
Cost per consumequantity (1 use per unit by default)
Feature pricingNot used — feature name is for entitlement/audit only
Activation modeOnline only
Seat limitNone — 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.

License Type — Usage-Based (MeteredCount).

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.

OutcomeRetry with the same operation id?
IsNetworkErrorYes — the charge may or may not have landed; the replay settles it
IsConcurrencyConflictYes — two calls raced on the wallet and this one lost
IsIdempotencyConflictNever — that id was already used for a different feature, quantity or device
IsInsufficientBalanceNo — nothing was charged. Top up, then start a new operation id
IsRetryableThe 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

  1. Create license with initial 500 uses.
  2. Consume any entitled feature ×1 → balance 499.
  3. Consume ×600 in one call → InsufficientBalance (402); balance unchanged at 499.
  4. Consume ×499 → balance 0.
  5. Next consume ×1 → InsufficientBalance (402).
  6. 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.

RoleWhat you see
Product owner / AdminRemaining uses, grant form, full ledger (consumes + grants)
End user (My Licenses)Read-only balance; consumption history where exposed
Member / ViewerRead-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:

ErrorCodeHTTPMeaning
InvalidRequest400Missing key, feature or operation id, or quantity <= 0
Unauthorized401Missing or invalid API key context
LicenseNotFound404No license for the key
NotMeteredLicense400Wrong license type
LicenseInvalid400Status is not Valid (revoked, suspended)
LicenseExpired403Calendar expiry passed — not covered by LicenseInvalid
ProductAccessDenied403The API key user cannot access the license's product
FeatureNotEntitled403Feature not in the entitlement sets (when sets are configured)
InvalidActivation400activationId is not an active activation on this license
ProductNotFound404The license has no resolvable product — inconsistent data, not a client error
WalletNotFound404The license has no meter wallet
InsufficientBalance402balance < cost — nothing was deducted
IdempotencyConflict409The operation id was already used for a different operation. Never retry
ConcurrencyConflict409Lost an optimistic-concurrency race. Retry with the same operation id
InternalError500Unexpected 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:

ErrorCodeRaised byMeaning
MissingOperationIdSDK — no request sentNo operation id was supplied, so nothing was charged
NetworkErrorSDK — the request failedThe 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:

QuestionUsage-BasedCredit-Based
What are you selling?A use counter (e.g. “500 exports”)A credit wallet (e.g. “10,000 credits”)
Cost per actionFlat — 1 use per consume (unless you pass a higher quantity)Variable — each feature has its own token cost
Setup before first consumeCreate license with initial use count onlySet TokenCost per feature, then consume
Best analogyPunch card — every action uses one punchPrepaid wallet — different services cost different amounts

See also