How invoice preview reflects spending minimums (charge-level and plan-level)

The invoice preview endpoint (POST /api/v1/invoices/preview) reflects both kinds of Lago spending minimum: the charge-level floor (min_amount_cents on a charge) and the plan-level minimum commitment. As of Lago v1.48.1 the preview adds a true-up for either type when usage falls below the floor, mirroring what real invoicing does. If you are on an earlier version, only the charge-level minimum appears in preview and the plan-level commitment has to be calculated by hand.

How the two minimums work in preview

A charge-level minimum is a floor on a single charge. When usage for that charge is below min_amount_cents, Lago adds a true-up fee to lift it to the floor, and the preview includes this because it runs the full charge fee calculation including true-up logic.

A plan-level minimum commitment is a floor across all of a subscription's usage for the period. When the period's combined fees fall below the commitment, the preview adds a true-up to lift the total to the floor, the same way real invoicing does at finalization.

So a preview total that looks high relative to raw usage is expected when either minimum is set: the floor is being applied correctly. A preview total that exceeds the configured floor itself is a different matter and worth investigating as a possible proration issue.

The one case where the commitment will not appear

On v1.48.1+ there is a single situation where the plan-level commitment legitimately does not show in preview: the first period of a pay-in-advance plan. The commitment reconciles a completed period, so on the very first period there is nothing yet to reconcile and no commitment true-up appears. The preview matches the invoice in this case too.

How to tell which minimum you have

Check GET /api/v1/plans/:code. A charge-level minimum appears as min_amount_cents on the relevant charge. A plan-level minimum commitment appears as the minimum_commitment object on the plan. Both are serialized in that response, so the plan payload tells you which floor or floors are in play and therefore what to expect from the preview.

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