Metered licenses and usage credits

Allocate usage units and charge them once for a licensed operation.

Plan requirement

Business includes metered licensing. Pro and lower plans receive PLAN_UPGRADE_REQUIRED (403). Enable Usage credits on your software plan and issue a metered license. A stored balance is retained after a platform downgrade, but granting/consuming credits requires an eligible effective subscription.

Credits are whole-number usage units, not euros, bank payments or automatic subscription invoices. There is no payment gateway for credits in the customer portal.

Add or adjust credits

Use a license’s Credits screen in the developer dashboard, or POST /api/v1/licenses/{license}/credits from a trusted backend. The management key needs licenses:write, the correct environment and product scope. Never ship it in an app.

jsonjson

{
  "type": "grant",
  "amount": 100,
  "idempotency_key": "allocation-order-123",
  "reason": "Initial usage allocation"
}

grant and refund add positive units; adjust allows positive or negative units but cannot take balance below zero. A credit refund returns units only; it does not refund a payment. Values must be safe whole numbers within ±9,007,199,254,740,991, subject to the operation’s sign rules.

Consume before doing work

With an activated license, send POST /api/v1/licenses/consume using its activation bearer token, X-Installation-ID, the current fingerprint, a positive integer amount and an idempotency_key. For floating licenses also send the current session_token.

jsonjson

{
  "amount": 1,
  "idempotency_key": "export-job-123",
  "reason": "Export",
  "fingerprint": "<current fingerprint object>",
  "session_token": "<only when this license uses shared seats>"
}

Verify the signed receipt in license, including credit_transaction and its amount, resulting balance, request-key hash and license/device binding. Successful responses include transaction_id, consumed, balance and replayed. The last successful consume may leave zero and still authorize that one completed charge; it is not permission for another job.

The debit and ledger row commit together under the license lock. Reusing the same request key and operation returns the original receipt without another debit. Reusing a key for different operation data returns IDEMPOTENCY_CONFLICT (409). The key is 8–190 characters: letters, digits, dot, colon, underscore or hyphen. The API accepts an omitted key, but provide and persist one for every billable job to make uncertain outcomes recoverable.

Failures and retries

INSUFFICIENT_CREDITS (402) means no charge was made and the job must not run. INVALID_CREDIT_AMOUNT (422), NOT_METERED_LICENSE (409) and CREDIT_LIMIT_EXCEEDED require correcting the request or policy. A lost network response is an uncertain outcome: deliberately retry the same operation with the same key. Do not create a new key, and do not automatically run the job twice because a charge was replayed.

The credit ledger deduplicates the charge, not execution of your application’s job. Keep your own job record/lock to deduplicate the work. Never expose keys, tokens, raw receipts or customer payloads in logs.

Balance and offline behavior

Matching SDKs provide an online signed balance read: Python/Rust get_balance(), Node.js/PHP getBalance(), C# GetBalanceAsync(). It uses validation; there is no separate public balance endpoint to invent. A replayed receipt carries the historical post-charge balance, so read again if you need the current value.

Metered permission and consumption are online-only. METERED_ONLINE_REQUIRED rejects cached/offline permission, even within a regular license grace window. Features never consume credits by themselves. Customers can view their balance and recent transactions in the portal, without granting or spending credits there.