Credit consumption and expiration

Credits are consumed by charges. Flat-fee and usage-based charges can settle against customer credits.

The settlement mode controls whether Metering & Billing consumes credits, invoices the customer, or both. You set it on the plan, and you can override it for an individual subscription when you create the subscription.

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, and no invoice overage is generated. If the credit balance covers the charge, the charge consumes credits like any other:

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

If the credit balance is insufficient, the charge isn’t blocked. Metering & Billing consumes the available credits, settles the uncovered amount as well, and the customer’s credit balance goes negative:

charge amount:       100 USD
credit balance:       40 USD
credits consumed:     40 USD
uncovered amount:     60 USD
invoice remainder:     0 USD
balance afterwards:  -60 USD

Negative balances

A negative balance under credit_only represents usage the customer has already consumed but not yet paid for with credits. It’s repaid by the next credits the customer receives: a new grant first covers the negative balance, and only the remainder increases the available balance. This happens as soon as the grant is created, even if the grant takes effect later.

balance before grant:  -60 USD
new grant:            +100 USD
repays negative:        60 USD
balance afterwards:     40 USD

If a customer has several negative amounts outstanding, new credits repay them in the order they were recorded. A grant restricted to specific features or plans only repays negative amounts from charges it’s eligible for.

A negative balance doesn’t create a separate invoice. If you need to limit overspending, monitor the customer’s balance and grant more credits, or use the credit_then_invoice settlement mode so that uncovered usage is invoiced.

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

priority asc
restricted before unrestricted
expires_at asc
stable movement order asc

This means:

1. Grants with lower priority values are consumed first.
2. For equal priority, grants restricted to specific features or plans are consumed before unrestricted grants. Shared credit stays available for other usage.
3. Credits that expire earlier are consumed first. Credits that never expire come last.
4. If all of these are equal, Metering & Billing uses stable movement order.

Only grants whose restrictions match the charge are eligible. For example, a grant restricted to input_tokens is never consumed by an output_tokens charge.

This order makes the result predictable and prevents avoidable expiration. If two grants have the same priority and restrictions, 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.

Charges consume credits when they’re booked. The booking time depends on the charge type:

• Usage-based charges book their consumption as the usage is recognized, which can be after the usage occurred.
• Flat-fee charges book their consumption at the start of the service period when paid in advance, and at the end when paid in arrears.

Until a charge is booked, its expected consumption shows up only in the live balance. Credits that expire before a charge is booked aren’t available to that charge.

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 booked, the credits it consumes are recorded as consumed movements. 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.