Skip to content

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.

FieldTypeRequiredDescription
namestringyesName of the balance type (e.g. "API Credits")
descriptionstringnoDescription
service_idstringyesThe service this balance type belongs to
disable_paygbooleannoIf true, balances of this type are prepaid only and cannot be switched to PAYG (default: false)
unit_singular_namestringnoSingular display name for this type's unit, e.g. "credit" (default: "unit")
unit_plural_namestringnoPlural display name for this type's unit, e.g. "credits" (default: "units")
unit_allow_decimalbooleannoWhether 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_daysintegernoDays 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_spendbooleannoIf 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 ​

FieldTypeRequiredDescription
customer_idstringyesThe customer who owns this balance
balance_type_idstringyesThe type of balance
current_balancedecimalautoCurrent amount. Prepaid balances are always >= 0. PAYG balances can go negative.
paygbooleannoWhether this balance is in pay-as-you-go mode (default: false)
limit_paygdecimalnoPer-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_amountdecimalnoPer-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.
statusenumautoACTIVE, PARTIALLY_FROZEN, or FROZEN
default_timeout_reservationintegernoDefault timeout in seconds for reservations (default: 172800 = 2 days)
max_timeout_reservationintegernoMaximum 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.60

Usage 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.60

See 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 ​

StatusDescription
PENDINGUsage recorded, not yet billed (PAYG only)
BILLED_PENDINGBilled to an order, but order not yet paid
BILLEDSuccessfully billed and paid
RESERVEDBalance reserved but not yet committed
DENIEDReserved usage was cancelled or timed out
REFUNDEDPreviously billed, now refunded
REVOKEDPreviously 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).

  1. Reserve - Deducts the estimated amount immediately and sets status to RESERVED. A timeout is set.
  2. 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.
  3. 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:

FieldDescription
amountFrozen amount (null = full freeze)
internal_reasonReason for the freeze
created_byUser who created the freeze
resolved_byUser who resolved the freeze
resolved_with_refundWhether 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 reasonTriggerResolved when
MANDATE_REVOKEDA PAYG balance has no valid linked mandate, or a previously linked mandate was revokedA new valid mandate is linked
PAYMENT_OVERDUEA PAYG billing order was not paid within payg_payment_grace_daysThe billing order is successfully paid