Credit-Based license
A Credit-Based license (MeteredToken, metering mode Token) is
always online. Customers share one credit wallet across all devices on the
license key. Each entitled feature deducts credits according to per-feature token pricing on
the product — not a flat “one use per call” like Usage-Based.
Shared wallet
One balance per license key — not per device.
Variable cost
Each feature has a TokenCost × quantity.
Usage tab
Balance, ledger, manual top-ups (owners).
Credit-Based license — for product owners
- Issue with initial credit balance and online validation (always online).
- Set per-feature token pricing via
PUT /api/meter/features/{featureId}/pricing. - Top up, adjust, set low-balance threshold, and reconcile from the license Usage tab or meter API.
- Inspect ledger for consumes, grants, and idempotent replays.
- No activation seat cap — many devices share one wallet.
Detailed wizard steps, pricing, and operator API routes are documented below.
Credit-Based license — for end users
Your organization shares a license key with a credit wallet. The app stays valid even at zero credits, but billable features fail until credits are added.
- Activate once — validation does not deduct credits.
- Each paid action (export, render, API call) spends credits per feature pricing.
- Insufficient balance — contact your admin to purchase more credits.
- Check remaining balance in-app if the integrator exposed
GetBalanceAsync.
When to choose Credit-Based
Choose Credit-Based when you sell a pre-paid pool of credits and different
features in your product should cost different amounts. The customer starts with a balance
(for example 10,000 credits). Each time they run a billable action, your app calls
ConsumeMeterAsync and the server deducts credits based on that feature’s configured price.
Think of it like a prepaid phone plan with variable call rates: one minute to country A costs 2 credits, one minute to country B costs 5 credits — same wallet, different prices per action.
Good fits
- API or SaaS with tiered actions — “10,000 API credits per month”; a simple read costs 1 credit, a heavy export costs 25.
- Document / OCR / AI products — “5,000 pages included”; OCR costs 10 credits per page, summary costs 40.
- Creative or compute tools — “1,000 render credits”; preview is cheap, 4K export is expensive.
- Top-up sales — customer buys another 5,000 credits when the wallet is low (manual grant from the Usage tab today).
How it behaves in LicenPro
- Dashboard label: Credit-Based. API enum:
MeteredToken. - Balance is shown in credits (shared across all devices on the license key).
- You must set a token cost per feature before consume works — inline on the product Features page, or via the metering API.
- Example: feature
ExportPdfpriced at 25 → one consume deducts 25 credits, not 1.
When to use Usage-Based instead
If every billable action should cost exactly one use — “500 exports included”, “1,000 API calls” —
and you do not need different prices per feature, use
Usage-Based (MeteredCount). It is simpler: no feature pricing step.
At a glance
| Property | Value |
|---|---|
| Backend enum | LicenseType.MeteredToken (value 6) |
| Dashboard label | Credit-Based |
| Metering mode | MeteringMode.Token |
| Balance unit | credits |
| Cost per consume | FeatureMeterPricing.TokenCost × quantity |
| Activation mode | Online only — offline is not available |
| Seat limit | None — any number of devices may activate; the wallet is the limit |
Key invariant
Balance is only checked and deducted in POST /api/meter/consume.
License validation, activation, and session connect never look at the balance.
A Credit-Based license can activate at zero credits; your app must call ConsumeMeterAsync when a
billable feature runs and handle InsufficientBalance (HTTP 402).
Create a Credit-Based license (dashboard)
Open Licenses → Generate License. Four steps: Activation → License Type → Basic Info → Details.
Step 1 — Activation
Select Online. Credit-Based is an always-online type — the wizard forces online mode and hides metered cards if Offline is selected.
Step 2 — License type
Select the Credit-Based card (“Variable cost per feature”). Subtitle explains the shared credit pool and manual top-ups.
Step 3 — Basic info
- Product and Software release (required).
- Issued to — end user assigned to the release (required for non-perpetual types).
- License name — internal label in lists and audit.
- Optional Entitlement set — when set, only entitled features can be consumed.
Step 4 — Details
- Initial credits balance (
initialMeterBalance) — required, must be > 0 (default in the form is often 10,000). - Notes — operator context (invoice, SKU, support ticket).
On save, the backend creates a MeterWallet with mode Token and writes an InitialGrant ledger row when balance > 0.
Create Credit-Based license, initial 10,000
└─ MeterWallet { mode: Token, balance: 10000 }
└─ UsageLedger { type: InitialGrant, amount: +10000, balanceAfter: 10000 }
Configure per-feature pricing (Credit-Based only)
Before clients consume a feature, set its token cost on the product.
API: PUT /api/meter/features/{featureId}/pricing (product owner / admin).
TokenCostmust be > 0.- Previous active pricing rows are deactivated; history is preserved.
- Consuming a feature with no active pricing returns
PricingNotConfigured(HTTP 422).
Note: Token cost is editable inline on the product Features page; the API above is the same path the dashboard uses.
Activation & sessions
- Always-online — activation and sessions are required like Floating.
- No activation seat cap —
EnforceSeatLimitOnActivationis false for metered types; many devices may share one key. - Activations and sessions appear in the dashboard for support visibility (optional attribution on consume via
hardwareId/activationId).
See Activations and Sessions platform guides.
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("ExportPdf");
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("ExportPdf", 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 credits, 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 |
IsPricingNotConfigured | No — the product owner must price the feature first |
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.
Consume request
| Field | Required | Notes |
|---|---|---|
licenseKey | Yes | Customer license key |
featureName | Yes | Must be entitled; must have active pricing |
idempotencyKey | Yes | Reuse on retry of the same logical operation |
quantity | No (default 1) | Cost = TokenCost × quantity |
hardwareId | No | Auto-detected by SDK when omitted |
activationId | No | Attribute usage to a device row |
Worked example
- Create license with initial 10,000 credits.
- Price feature
"render"at TokenCost 40. - SDK consumes
render×1 → cost 40 → balance 9,960. - Retry with same
idempotencyKey→ replay, balance still 9,960. - Consume unpriced feature →
PricingNotConfigured(422). - Owner grants +5,000 → balance 14,960, ledger
AdminGrant.
Usage tab (license detail)
Open a Credit-Based license → Usage tab.
| Role | What you see |
|---|---|
| Product owner / Admin | Remaining balance, Grant balance form (amount, reason, external reference), full usage ledger |
| Assigned end user (My Licenses → detail) | Read-only balance card; ledger without grant actions |
| Member / Viewer | No grant UI; read-only where permitted |
Ledger entry types: InitialGrant, Consume (negative amount), AdminGrant, Adjust.
Top-ups are manual only — there is no payment gateway integration in the current release.
Analytics
Institution analytics includes a metered usage section from
GET /api/statistics/meter-usage: metered license counts, total balance remaining,
consumed/granted in the period, low-balance alerts, daily consumption trend, top features, 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 |
PricingNotConfigured | 422 | No active TokenCost for this feature |
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 |
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 |
Credit-Based vs Usage-Based
Use this quick guide if you are deciding between the two metered types:
| Question | Credit-Based | Usage-Based |
|---|---|---|
| What are you selling? | A credit wallet (e.g. “10,000 credits”) | A number of actions (e.g. “500 exports”) |
| Cost per action | Varies by feature — you set each feature’s token price | Always the same — usually 1 use per consume |
| Setup before first consume | Configure TokenCost per feature | Nothing extra — just create the license with an initial use count |
| Best analogy | Prepaid credits with different prices per service | “Includes 500 uses” — each button click counts as one |
