How to preview how a coupon will be applied before an invoice is finalized

Coupons are applied to an invoice at finalization, so their effect is not visible in the customer's UI until the invoice exists. To see how a coupon will affect an invoice before it is finalized, call the invoice preview endpoint, which returns a simulated invoice with the discount already applied.

How invoice preview works

A POST request to /api/v1/invoices/preview returns a simulated invoice without creating or persisting anything. The response itemizes the fee line items, the coupons_amount_cents discount, and any applied credits, and totals the projected amount. Nothing is billed and no invoice is stored. Invoice preview is a premium feature on Lago Cloud and Self-Hosted Premium.

There are two ways a coupon shows up in the preview:

• A coupon already applied to the customer. If the customer has an active applied coupon, the preview reflects it automatically, using the same priority ordering as a real invoice. You do not need to pass anything extra.

• A coupon passed in the request. If you want to simulate a coupon that is not yet applied to the customer, include a coupons array in the request body. Each entry describes the coupon (code, coupon_type, amount_cents or percentage_rate, frequency, and so on). If the code matches an existing coupon in your organization, that coupon's configuration is used; otherwise Lago builds a temporary coupon from the properties you provide.

The coupons array in the request acts as a fallback. When the customer already has an active applied coupon, that coupon takes precedence and any coupons array in the request body is not applied. This precedence is an implementation detail and may change without notice. To simulate a different coupon, preview against a customer who has no active applied coupon.

How to preview the coupon

Send a POST request to /api/v1/invoices/preview with the customer's external_id.

If the customer already has an active applied coupon, the response reflects it with no coupons parameter needed. To simulate a coupon that has not been applied yet, add a coupons array describing it. Either way, the response shows the projected total and the coupons_amount_cents discount, so you can verify how the coupon applies before the billing period closes.

For the request payloads, including the coupon fields, see the invoice preview guide: https://getlago.com/docs/guide/invoicing/previews

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