Why adding seats charges the full new total instead of just the delta

A customer is billed for the full new seat count (e.g. 12 seats prorated) when they add seats, rather than only the incremental seats added (e.g. 2 seats prorated). This happens when the metric uses sum_agg and the event sent on seat expansion contains the new absolute total instead of the delta. Lago treats every event value as an increment, so sending 12 when the intent was "total is now 12" is interpreted as "add 12 more."

How sum_agg works

sum_agg accumulates the numeric value of every event in the billing period. Each event's field_name value is treated as a quantity to add to the running total, not as a snapshot of the current state.

If a customer starts at 10 seats (+10) and you send a second event with {"seats": "12"} to represent a seat expansion, Lago adds 12 to the existing 10 and bills for 22 seats.

A corrective negative event ({"seats": "-10"}) sent afterward will fix the running Usage total shown in the UI, but any invoice that was already finalized before the correction arrived is unaffected. The credit only flows into the next periodic invoice.

How to resolve the issue

The overbilled invoice cannot be retroactively corrected by the negative event. You need to issue a manual credit note for the overbilled amount. This can be done from the invoice detail page in the UI (Actions → Create credit note) or via the credit notes API endpoint. Scope the credit note to the difference between what was charged and what should have been charged for the period.

If the customer also wants a refund rather than a credit balance, set the credit note refund_amount_cents accordingly.

How to prevent this from happening again

When using sum_agg for seat-based or quantity-based metrics, always send the delta — the change in quantity — not the new absolute total. For a seat expansion from 10 to 12, send {"seats": "2"}. For a reduction from 12 to 10, send {"seats": "-2"}. If your system natively tracks absolute counts, compute the delta before sending the event to Lago. Consider switching to max_agg or unique_count_agg if your use case is better described as "current state" rather than "accumulated usage."

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