How wallet credits are applied when an invoice is finalized

Last updated: May 13, 2026

Wallet credits are applied during invoice finalization, not when events are ingested. Credits must be available in the wallet when finalization runs. They cannot be applied retroactively.

How wallet credit application works

When an invoice is finalized, Lago applies available credits in this order:

  1. Progressive billing credits

  2. Coupon credits

    1. NOTE: The coupon is applied pre-tax, so it reduces both the fee and the resulting tax. This means the wallet covers less than invoice_total - coupon_amount; it covers (fee - coupon) + tax_on_remaining.

  3. Credit note credits

  4. Wallet credits

Wallet credits cover whatever total remains after the earlier credits are applied, not the raw invoice total. If the remaining balance is zero before wallet credits are reached, no wallet credits are consumed. For the wallet credit step itself, there are three possible outcomes:

  • Wallet balance is less than the remaining amount: Available credits are fully consumed, and the remainder is charged to the configured payment provider.

  • Wallet balance equals the remaining amount: The invoice total due becomes zero, and no payment attempt is made.

  • Wallet balance exceeds the remaining amount: The invoice is fully covered, and the remaining credits stay in the wallet.

If a customer has multiple wallets, they are applied in priority order (lowest priority value first, then by creation date). Only active (non-terminated) wallets are used.

Paid vs. granted credits

When you top up a wallet with paid credits via the API, those credits are initially in a pending state and a top-up invoice is generated. Credits do not become available until that invoice is paid. Granted credits settle immediately. If you're funding a wallet close to a billing date using paid credits, ensure payment completes before finalization runs.

How to confirm the cause

Check the customer's wallet balance and status before and after invoice finalization. If the wallet was empty or terminated at finalization time, no credits were applied. Also confirm that any recent top-up was paid and settled. A pending top-up invoice means the credits are not yet available.

How to resolve the issue

Ensure the wallet is funded and settled before the billing date. To top up a wallet manually:

POST /api/v1/wallet_transactions

Pass granted_credits for credits that settle immediately, or paid_credits for credits that require a payment to complete.

How to prevent this from happening again

Configure a recurring wallet top-up rule on the wallet. Two trigger types are available:

  • Interval: tops up on a fixed schedule (weekly, monthly, quarterly, etc.)

  • Threshold: tops up automatically when the balance drops below a defined minimum

Both support a fixed top-up amount or a target-balance method that fills the wallet to a specified level.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.