Credit balance model

The credit balance model has two balance types:

• Settled balance is the balance from committed ledger movements. It is the durable record of what has happened.
• Pending balance is a live view that starts from the settled balance and accounts for open charges that may still consume credits.

Settled balance comes from committed credit movements. If a customer receives 100 USD and consumes 30 USD, the settled balance is 70 USD.

+ 100 funded 
 - 30 consumed
--------------
   70 settled balance

If you query a balance at a timestamp, Metering & Billing includes movements visible at or before that timestamp, because a settled balance references a point in time. Future movements, including future expiration, don’t affect an earlier balance.

Example:

T1: grant 100 credits
T5: consume 30 credits
T10: expire unused credits

The settled balance changes depending on the query timestamp:

Settled balance is the right model for audit and history: the same timestamp always reflects the same visible ledger state.

Live balance is a pessimistic operational view. It accounts for open charges that may still consume credits, even before those charge movements are finalized into the settled balance.

For example, assume a customer has 100 USD settled credits and an open charge is expected to consume 25 USD. The settled balance is still 100 USD, but the pending balance is 75 USD, so the system doesn’t overstate usable credit.

settled balance:         100
open charge impact:      -25
pending balance:          75

This distinction matters when you display balances:

• Use settled balance when the user needs an audit-style view of committed movements.
• Use live balance when the user needs a conservative “can this customer spend more?” view.

  Pending grants

Pending grants describes credits that have been granted but are not yet written to the ledger, or are written to the ledger with a future booked time.

Credit balances are currency-specific. For example, a USD grant increases the customer’s USD credit balance, while a EUR charge consumes from the customer’s EUR credit balance.

Do not merge currencies in user-facing balance displays unless your product explicitly converts them. Treat each currency as a separate balance.

Expiration is visible only when the expiration time is visible to the query.

If a customer receives 100 credits at T1 and those credits expire at T10, the settled balance is still 100 before T10. At T10, any unused amount expires and the settled balance changes.

If the customer used 30 credits before expiration, only the remaining 70 credits expire.

T1:  +100 funded
T5:   -30 consumed
T10:  -70 expired

The consumed 30 credits don’t expire because they were already applied.