Why pricing group keys cannot be hidden from invoices

Pricing group keys have no display_in_invoice option, so the lines they create cannot be hidden from an invoice. Presentation group keys do have that option. The difference is structural: a pricing group key creates one fee per grouping value, and every fee carries an amount that sums into the invoice total, so hiding one would leave an invoice whose line items do not add up to it.

For what each feature does and how to configure them, see the grouping keys guide in the Lago documentation. This article covers only why the display toggle exists on one and not the other, and the behavior that is easy to miss.

How the two features differ

Because each pricing group is a real fee, it has its own amount, its own applied tax lines and its own credit note items. Hiding one would produce a subtotal that does not reconcile with the visible lines, and a refundable amount with no line to refund against. A presentation breakdown carries only the grouping value and a unit count, so suppressing it has no effect on any total.

Where each one appears on the invoice

Pricing groups appear in the main line item table, with the grouping values appended to the metric name as Metric name • value1 • value2, each line showing its own units, unit price, tax and amount.

Presentation breakdowns appear on a separate page at the end of the invoice, under a "Usage breakdown by ..." heading, listing units only with no amounts. If you enable a presentation group key and do not see it on the invoice, check the final pages of the PDF before assuming it did not apply.

What to do if you do not want the lines on the invoice

If per-group pricing is not actually required, move the key from pricing_group_keys to presentation_group_keys. The charge collapses back to a single fee line, and the per-group detail moves to the hideable breakdown section. The tradeoff is that you lose per-group amounts, per-group unit prices and the ability to credit a single group.

If per-group pricing is required, there is no way to hide the resulting lines. invoice_display_name is set at charge level and cannot be varied per group, so it does not help here.

Behavior worth knowing before you configure this

The following are implementation details observed in the current Lago codebase and are subject to change.

• Presentation group keys inside a charge filter are silently ignored. If you send presentation_group_keys in a filter's properties, the API returns a success response and the key is dropped. Set it on the charge, where it applies across all filters. Pricing group keys, by contrast, can be set per filter.

• Omitting options over the API hides the breakdown rather than showing it. Only breakdowns with display_in_invoice set to true are rendered, so a charge created over the API without options produces a hidden breakdown. The dashboard makes the choice mandatory, so a charge created in the UI and a charge created over the API can behave differently. If you do send options, it must contain exactly display_in_invoice. An empty options object is rejected with a 422.

• display_in_invoice: false still returns the breakdown on the usage endpoints. It suppresses the breakdown on the invoice PDF and in invoice and fee API responses, but current and projected usage responses still include it. This is useful if the goal is internal analytics without customer-visible detail.

• Presentation group keys are not applied to custom aggregation. Billable metrics using a custom aggregation produce no presentation breakdowns.

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