Why a pay-in-advance charge set to not invoice never deducts from the wallet

If usage events are ingesting correctly but a metered charge never appears on an invoice and the wallet balance never drops, the charge is almost certainly set to pay in advance with its invoicing strategy set to not invoice any fees. That combination creates fees but never attaches them to an invoice, and in Lago a wallet is only ever debited by an invoice. So the fees sit pending forever and no credit is consumed. This is the charge behaving as configured, not a fault.

How wallet drawdown actually works

A prepaid wallet is reduced when an invoice is finalized and credits are applied to it. Nothing else moves the real balance. A standalone fee with no invoice, a usage event on its own, or a pending fee cannot touch the wallet.

Pay in advance and pay in arrears are set per charge, and either can work with a wallet. What matters is the charge's invoicing strategy, which has three options:

• Invoice each fee upon event reception (the default when a charge is pay in advance). Each event produces its own invoice immediately, and that invoice deducts from the wallet. Pay in advance is safe with wallets in this mode.

• Do not invoice any fees (invoiceable: false, a premium option). Fees are created and tracked but are never attached to any invoice, so they never trigger a wallet debit. This is the setting that produces the stuck state.

• Regroup all fees in a single invoice at the end of the period (regroup_paid_fees: invoice, which requires pay in advance and non-invoiceable). Fees are swept into a separate end-of-period invoice, but only fees already marked as paid are picked up, and that invoice is finalized as already paid. It is meant for payments collected outside Lago, so it does not deduct from the wallet either.

The takeaway: a charge told never to invoice can never consume wallet credit, in any of these modes, because there is no invoice to apply credit to. Pay in arrears, or pay in advance with per-event invoicing, are the configurations that debit the wallet.

The ongoing balance shown in the wallet UI is a projection of current-period usage and does not represent settled credit. It also deliberately nets out pay-in-advance charge usage, which matters for spotting this problem (see below).

How to confirm you are in this state

Two checks:

• GET /api/v1/plans/{code} and inspect each charge. The stuck combination is pay_in_advance: true together with invoiceable: false. In the UI this shows as an invoicing strategy of "Do not invoice any fees".

• GET /api/v1/fees?payment_status=pending for the customer. The stranded fees show invoice_id: null. They accumulate and never settle.

How to fix it

Once a plan has any subscription attached, the pay_in_advance and invoiceable settings on an existing charge become locked. The UI greys the toggle out, and PUT /api/v1/plans/:code returns a success response but silently leaves those two fields unchanged. Any customer hitting this problem already has a subscription on the plan by definition, so editing the charge in place does nothing, even though it looks like it worked. Do not rely on that path.

Two approaches actually change the behavior:

1. Recreate the charge. Delete the charge and add it back with the correct settings, either in the UI or via DELETE then POST /api/v1/plans/:plan_code/charges. Charge deletion is not blocked by existing subscriptions. This applies to every subscription on the plan immediately, so only use it if all customers on the plan should change.

2. Create a corrected plan and migrate. Build a new plan with the right charge configuration and move the affected subscriptions to it. This is the safer choice when only some customers should be changed.

Either way, the fees already stranded as pending do not self-heal. Changing or recreating the charge fixes future usage but does not retroactively invoice the backlog. Decide with the customer how to handle it: write it off, bill it through a one-off add-on invoice, or, if you were using the regroup strategy, mark the pending fees paid so they get swept into the period-end invoice. Note that this last option still will not deduct from the wallet, since the regrouped invoice is finalized as already paid. Validate any ledger correction before running it.

What to watch for

The symptom is not a divergence between ongoing and actual balance. Because the ongoing balance projection already subtracts pay-in-advance charge usage, both balances sit flat in this failure mode, so watching for them to drift apart will hide the problem rather than reveal it. The real signals are:

• The wallet balance never decreases even though usage events are being ingested.

• Pending fees with no invoice pile up on the customer.

• No per-event invoices appear, when per-event billing was expected.

Getting the configuration right up front

The durable lesson is to set charge invoicing correctly before the first subscription attaches, because these settings lock afterward and can then only be changed by recreating the charge or the plan. With a prepaid wallet, either bill the charge in arrears, or bill it in advance with "Invoice each fee upon event reception". Avoid "Do not invoice any fees" for any charge you expect to draw down a wallet.

The code-level details behind the locking and the fee handling are implementation specifics that can change without notice; the observable behavior above is what to rely on.

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