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. A customer’s fiat credits are held in the customer’s currency, for example USD. A customer can also hold balances in custom currencies, such as tokens, API calls, or compute units you define for your organization. Charges consume credits from the matching currency balance.

The purchase that funds a grant always settles in a fiat currency, even when the granted balance is in a custom currency. Metering & Billing converts custom-currency charges on a fiat invoice through the currency’s cost basis. Under credit_then_invoice, any credits the customer holds in the invoice’s fiat currency can then cover part of that converted amount.

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. The balances include: a settled balance from committed ledger movements, a live balance that also accounts for open charges, and a pending amount, which shows the total of granted credits that haven’t taken effect yet.
• Charges consume credits. The settlement mode on the plan controls whether credits are applied before invoicing or whether charges are settled only against credits.
• Transaction history explains balance changes. Credit transaction history shows customer-facing movements: funded, consumed, expired, and voided.

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. You set the settlement mode on the plan, and you can override it for an individual subscription when you create the subscription. 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.

A negative balance is repaid by the next credits the customer receives. A new grant first covers the negative balance, and only the rest of the grant increases the available balance. For details, see Negative balances.

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.