---
title: "Metered licenses and usage credits"
description: "Allocate usage units and charge them once for a licensed operation."
slug: "/docs/v1/licensing/credits"
section: "Licensing models"
order: 903
audience: "all"
level: "intermediate"
last_updated: "2026-10-25"
version: "v1"
related: ["/docs/v1/licensing/platform-plans", "/docs/v1/sdks/compatibility"]
draft: false
---
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.

```json
{
  "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`.

```json
{
  "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.