Credit consumption and expiration

Credits are consumed by charges. A charge can represent a flat fee, usage-based spend, or another billable item configured to settle with customer credits.

The rate card’s settlement mode controls whether Metering & Billing consumes credits, invoices the customer, or both.

Credit then invoice

With credit_then_invoice, Metering & Billing applies credits first. If the customer does not have enough credits, the remaining amount is invoiced.

charge amount:       100 USD
credit balance:       40 USD
credits consumed:     40 USD
invoice remainder:    60 USD

This is the common prepaid-plus-overage model. Customers can use prepaid credits, but usage is not blocked if credits run out.

Credit only

With credit_only, the charge is settled exclusively against credits. If the credit balance is insufficient, the charge is blocked and no invoice overage is generated.

charge amount:       100 USD
credit balance:      100 USD
credits consumed:    100 USD
invoice remainder:     0 USD

When a customer has multiple grants in the same currency, Metering & Billing consumes credits in a deterministic order:

priority asc
expires_at asc
stable movement order asc

This means:

1. Grants with lower priority values are consumed first.
2. For equal priority, credits that expire earlier are consumed first.
3. If both are equal, Metering & Billing uses stable movement order.

This order makes the result predictable and prevents avoidable expiration: if two grants have the same priority, the one expiring sooner is used first.

Assume a customer has three grants:

The customer incurs a 90 credit charge. Metering & Billing consumes:

Grant A is consumed first because it has the same priority as B but expires earlier. Grant C is untouched because its priority value is higher.

Credit expiration removes unused credits from a customer balance at the grant’s expiration time. Credits that were already consumed don’t expire later, because they are no longer part of the customer’s remaining balance.

Basic expiration

Assume a customer receives 100 credits that expire at T10. If the customer does not use any credits before T10, all 100 credits expire at T10.

T1:  +100 funded
T10: -100 expired

The settled balance is 100 before T10 and 0 at T10.

Partial usage before expiration

If the customer uses some credits before expiration, only the unused amount expires.

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

The customer used 30 credits, so those 30 credits don’t expire. The remaining 70 credits expire at T10.

Why expiration follows consumption order

When multiple grants exist, Metering & Billing consumes credits in a deterministic order. That order also determines which future expiration is reduced when credits are used.

If one grant expires earlier than another grant with the same priority, the earlier-expiring grant is consumed first. That means its future expiration is reduced first.

If the customer consumes 30 credits before T10, those credits come from grant A. At T10, only 20 credits from A expire.

T1:  grant A +50, expires T10
T1:  grant B +50, expires T20
T5:  consume 30 from A
T10: expire 20 from A

Grant B is still available because A had the same priority and an earlier expiration.

When a charge is processed, a consumed movement is recorded for each grant drawn from. When a grant expires, an expired movement is recorded for the remaining unused amount.

Both movement types appear as negative values in credit transaction history. Expiration is visible only when the expiration time is visible to the query: a balance read before the expiration timestamp doesn’t include that future expiration.