Appearance
Service Balances
A service balance tracks a customer's credit or usage for a specific resource within a service. Each balance is linked to a Balance Type that defines what the balance represents and how it behaves.
A customer can have at most one balance per balance type. Service balances can operate in prepaid mode (credits bought upfront) or pay-as-you-go mode (usage tracked and billed monthly). This page covers prepaid balances and the shared infrastructure used by both modes. For PAYG, see Pay-As-You-Go.
Balance Types
A balance type defines a category of balance for a service. It controls whether PAYG is allowed and how overdue billing is handled.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Name of the balance type (e.g. "API Credits") |
description | string | no | Description |
service_id | string | yes | The service this balance type belongs to |
disable_payg | boolean | no | If true, balances of this type are prepaid only and cannot be switched to PAYG (default: false) |
unit_singular_name | string | no | Singular display name for this type's unit, e.g. "credit" (default: "unit") |
unit_plural_name | string | no | Plural display name for this type's unit, e.g. "credits" (default: "units") |
unit_allow_decimal | boolean | no | Whether usage can be billed in fractional units. If false, cost is always rounded up to the next whole unit - see Whole-Unit Billing (default: true) |
payg_payment_grace_days | integer | no | Days after a PAYG billing order is created before the balance is frozen for non-payment. If not set, no automatic freeze is applied. |
excluded_from_referral_spend | boolean | no | If true, usage of this balance type never counts toward a customer's cumulative spend in the referral program (default: true - the opposite of the equivalent article category flag, since PAYG usage is typically incidental rather than a deliberate purchase) |
PAYG limits and free allowances
Overdraft limits and monthly free allowances are not set on the balance type. They are defined on the PAYG plan and snapshotted onto the activation when PAYG is activated. Individual balances can optionally override these values - see limit_payg and monthly_free_amount below.
Balance Fields
| Field | Type | Required | Description |
|---|---|---|---|
customer_id | string | yes | The customer who owns this balance |
balance_type_id | string | yes | The type of balance |
current_balance | decimal | auto | Current amount. Prepaid balances are always >= 0. PAYG balances can go negative. |
payg | boolean | no | Whether this balance is in pay-as-you-go mode (default: false) |
limit_payg | decimal | no | Per-balance overdraft limit override for PAYG mode. Takes precedence over the limit defined on the PAYG plan. If not set, the plan's limit applies. |
monthly_free_amount | decimal | no | Per-balance monthly free allowance override for PAYG mode. Takes precedence over the allowance defined on the PAYG plan. If not set, the plan's allowance applies. |
status | enum | auto | ACTIVE, PARTIALLY_FROZEN, or FROZEN |
default_timeout_reservation | integer | no | Default timeout in seconds for reservations (default: 172800 = 2 days) |
max_timeout_reservation | integer | no | Maximum allowed reservation timeout in seconds |
Prepaid Balances
In prepaid mode (payment_mode = PREPAID):
- The balance must always stay >= 0.
- The customer buys credits upfront, typically via article balance top-ups.
- Usage is deducted immediately. If the balance is insufficient, the usage is denied.
Example
A customer has a prepaid "API Credits" balance with 100 credits. They make API calls that consume 70 credits. Their balance is now 30. If they attempt a call that costs 50 credits, it is denied because the remaining balance is insufficient.
Automatic Top-Ups via Articles
Articles and extensions can be configured with balance top-ups. When a customer purchases such an article, their balance is automatically topped up by the configured amount. If the order is later revoked, the top-up is reversed.
Usage Tracking
When a customer consumes resources, a Balance Usage is created. How the cost is calculated depends on whether the balance is prepaid or PAYG.
Prepaid: Usage Categories
Prepaid balances use Usage Categories to define the cost of each type of consumption. A Usage Category belongs to a Balance Type and has a price_per_unit. Each Balance Usage contains one or more Usage Items, each referencing a category and a unit count. The cost is units_used × price_per_unit.
This allows fine-grained billing within a single usage event. For example, one API call might consume both input tokens and output tokens at different rates:
plain
Balance Usage
├── Usage Item: "Input Tokens" × 800 → 800 × €0.001 = €0.80
└── Usage Item: "Output Tokens" × 200 → 200 × €0.003 = €0.60Usage Categories have no currency - they represent abstract credit units. The monetary value of a credit is determined by the article price the customer paid to top up their balance.
PAYG: Plan Pricing
PAYG balances use the same items[] API as prepaid balances. Each item references a Usage Category and a unit count. The cost per item is units_used × price_per_unit, where price_per_unit comes from the active PAYG plan's price entry for that category and the customer's country - not from the Usage Category itself. The price_per_unit on a Usage Category is only relevant for prepaid; for PAYG it must be NULL.
plain
Balance Usage
├── Usage Item: "Input Tokens" × 800 → 800 × €0.001 = €0.80 (PAYG plan price, customer's country)
└── Usage Item: "Output Tokens" × 200 → 200 × €0.003 = €0.60See Pay-As-You-Go for details on plan pricing, free allowances, and overdraft limits.
Whole-Unit Billing
By default (unit_allow_decimal = true), usage cost can be fractional - e.g. 0.45 credits. If the balance type sets unit_allow_decimal = false, cost is always rounded up to the next whole unit before it's deducted, so a usage of 0.01 units is billed as 1 unit. This never under-bills. It applies to both prepaid and PAYG costs. For PAYG usage with a free allowance, the allowance is matched against the cost before rounding, so a usage fully covered by the free allowance is always billed as exactly 0 - it is not first inflated by rounding the gross cost up.
Usage Statuses
| Status | Description |
|---|---|
PENDING | Usage recorded, not yet billed (PAYG only) |
BILLED_PENDING | Billed to an order, but order not yet paid |
BILLED | Successfully billed and paid |
RESERVED | Balance reserved but not yet committed |
DENIED | Reserved usage was cancelled or timed out |
REFUNDED | Previously billed, now refunded |
REVOKED | Previously billed, now revoked |
Sufficiency Check
Before creating a usage, you can check whether a balance has sufficient funds without deducting anything. The API returns a simple boolean. A frozen balance always fails the sufficiency check regardless of the current amount.
Use idempotency keys when creating usage
Creating a balance usage deducts money immediately - if your request times out or the connection drops, you can't tell whether the deduction went through without checking. Send an Idempotency-Key with every usage-creation call so a safe retry replays the original result instead of deducting twice.
Reservations
Reservations allow you to hold balance before committing to a final amount - useful when the actual cost is not known upfront (e.g. an LLM call whose token count is unknown until it completes).
- Reserve - Deducts the estimated amount immediately and sets status to
RESERVED. A timeout is set. - Complete - Finalizes with the actual amount. If the actual cost is lower, the difference is returned to the balance. If higher, the additional amount is deducted.
- Cancel - Releases the reserved amount back to the balance. Status becomes
DENIED.
Expired reservations are automatically cancelled and refunded every 5 minutes.
When to use reservations
Reserve balance when a user triggers an operation whose cost you will only know after it completes - for example, before sending a prompt to an LLM. Complete the reservation once you know the actual token count.
Reserve, complete, and cancel all accept an idempotency key
Reserve creates a new reservation on every call, so a naive retry after a dropped response reserves the amount twice - use an Idempotency-Key here for the same reason as creating usage.
Complete and cancel work differently: both require the usage to still be RESERVED, so a plain retry after a genuine success already fails on its own with an error, rather than settling twice - the domain logic prevents the double-deduction either way. The benefit of an idempotency key here is different: instead of that retry surfacing as an error to you, it transparently returns the original successful response. This only helps once the first call has actually finished - a retry that arrives while the first is still processing gets a 409 either way.
Balance Freezes
Balances can be frozen to prevent any usage. Two types:
- Full freeze - Sets balance status to
FROZEN. No usage is allowed. The current balance amount is not deducted. - Partial freeze - Deducts a specific amount immediately and sets status to
PARTIALLY_FROZEN. The remaining balance can still be used.
Each freeze records who created it, why, and how it was resolved:
| Field | Description |
|---|---|
amount | Frozen amount (null = full freeze) |
internal_reason | Reason for the freeze |
created_by | User who created the freeze |
resolved_by | User who resolved the freeze |
resolved_with_refund | Whether the frozen amount was returned on resolution |
When a freeze is resolved:
- With refund - The frozen amount is returned to the balance.
- Without refund - The frozen amount is permanently kept.
When to use each type
Full freezes are for security or compliance situations (e.g. suspected fraud). Partial freezes are designed to lock only the amount associated with a specific outstanding order, so the customer retains access to any remaining balance.
Automatic Freezes
Some freezes are created automatically by the system:
| System reason | Trigger | Resolved when |
|---|---|---|
MANDATE_REVOKED | A PAYG balance has no valid linked mandate, or a previously linked mandate was revoked | A new valid mandate is linked |
PAYMENT_OVERDUE | A PAYG billing order was not paid within payg_payment_grace_days | The billing order is successfully paid |