Prepaid credits

Credits are customer-specific value that can be used to pay for charges. They are useful for prepaid plans, promotional balances, migration credits, enterprise commitments, or any workflow where a customer consumes a balance before paying by invoice.

A credit balance is always tied to a customer and a currency. For example, a customer can have a USD credit balance and an EUR credit balance. Charges consume credits from the matching currency balance.

For an end-to-end tutorial on setting up prepaid credits, see Get started with prepaid credits.

The credit system works as follows:

• Credit grants add credits to a customer balance. A grant can be promotional, funded through a Metering & Billing invoice, or funded externally.
• Balances show how much credit the customer has. There is a settled balance from committed ledger movements, and a pending balance that accounts for open charges.
• Charges consume credits. The settlement mode on the rate card controls whether credits are applied before invoicing or whether the full charge must be covered by credits.
• Transaction history explains balance changes. Credit transaction history shows customer-facing movements: funded, consumed, and expired.

Credits flow through a lifecycle of funding, consumption, and expiration. The following terms describe the key entities and states involved:

Credits are not a mutable counter. Metering & Billing records credit movements over time. When something changes, such as usage being corrected or credit expiring, the system records another movement instead of rewriting the old one. The balance is the result of the movements that are visible at the time you query it.

Assume a customer receives 100 USD in credits:

grant 100 USD credits

The customer’s settled credit balance becomes 100 USD. If the customer later uses 30 USD of credits, the balance becomes 70 USD:

grant 100 USD credits
consume 30 USD credits
remaining settled balance: 70 USD

If the original grant expires and 70 USD remains unused, the unused amount expires and the balance becomes 0 USD:

grant 100 USD credits
consume 30 USD credits
expire 70 USD unused credits
remaining settled balance: 0 USD

The customer-facing transaction history shows the same story as signed movements:

To learn more about movements and transaction history, see Credit transaction history.

Billing charges apply credits. When a charge is raised against a customer, Metering & Billing uses the settlement mode to determine how to apply credits:

The customer’s credit balance, the charge’s settlement mode, and the grant’s expiration and priority rules together determine how much credit is consumed.

For details on draw-down order and expiration behavior, see credit consumption and expiration.

For details on how Metering & Billing keeps credit balances correct through a double-entry ledger, immutable movements, and deterministic consumption order, see Correctness guarantees.