LicenPro
DocumentationCredit-Based

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 ExportPdf priced 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

PropertyValue
Backend enumLicenseType.MeteredToken (value 6)
Dashboard labelCredit-Based
Metering modeMeteringMode.Token
Balance unitcredits
Cost per consumeFeatureMeterPricing.TokenCost × quantity
Activation modeOnline only — offline is not available
Seat limitNone — 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.

License Type — Credit-Based (MeteredToken).

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).

  • TokenCost must 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 — EnforceSeatLimitOnActivation is 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.

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
IsPricingNotConfiguredNo — the product owner must price the feature first
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.

Consume request

FieldRequiredNotes
licenseKeyYesCustomer license key
featureNameYesMust be entitled; must have active pricing
idempotencyKeyYesReuse on retry of the same logical operation
quantityNo (default 1)Cost = TokenCost × quantity
hardwareIdNoAuto-detected by SDK when omitted
activationIdNoAttribute usage to a device row

Worked example

  1. Create license with initial 10,000 credits.
  2. Price feature "render" at TokenCost 40.
  3. SDK consumes render ×1 → cost 40 → balance 9,960.
  4. Retry with same idempotencyKey → replay, balance still 9,960.
  5. Consume unpriced feature → PricingNotConfigured (422).
  6. Owner grants +5,000 → balance 14,960, ledger AdminGrant.

Usage tab (license detail)

Open a Credit-Based license → Usage tab.

RoleWhat you see
Product owner / AdminRemaining 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 / ViewerNo 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:

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
PricingNotConfigured422No active TokenCost for this feature
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

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

Credit-Based vs Usage-Based

Use this quick guide if you are deciding between the two metered types:

QuestionCredit-BasedUsage-Based
What are you selling?A credit wallet (e.g. “10,000 credits”)A number of actions (e.g. “500 exports”)
Cost per actionVaries by feature — you set each feature’s token priceAlways the same — usually 1 use per consume
Setup before first consumeConfigure TokenCost per featureNothing extra — just create the license with an initial use count
Best analogyPrepaid credits with different prices per service“Includes 500 uses” — each button click counts as one

See also