How to detect billing period rollovers without subscription.updated

Lago intentionally does not fire subscription.updated when current_billing_period_started_at and current_billing_period_ending_at change at renewal. If these fields changed on every renewal, Lago would send a subscription.updated event for every active subscription simultaneously which would overwhelm integrators. As a result, billing period date changes on renewal are silent from a webhook perspective.

How to detect period rollover

The correct approach is to listen to invoice events instead of subscription.updated. When a billing period rolls over, Lago generates an invoice. The following events are reliable signals that a new billing period has started:

• invoice.drafted fires when the invoice moves to draft status at the start of the new period (if a grace period is configured).

• invoice.created fires when the invoice is finalized and ready.

Both events include the subscription object with current_billing_period_started_at and current_billing_period_ending_at, so you can extract the new period boundaries directly from the invoice webhook payload without making an additional API call.

Implementation pattern

In your webhook handler:

1. Listen for invoice.drafted or invoice.created with invoice_type = subscription.

2. Extract the subscription's current_billing_period_started_at from the payload.

3. Use this as the signal that a new billing period has begun for that subscription.

What subscription.updated does fire on

subscription.updated is sent for explicit subscription changes: plan upgrades or downgrades, changes to ending_at, name updates, and similar mutations. It is not sent for automatic period rollovers. If you need to track period changes alongside explicit subscription mutations, combine both event types in your handler.

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