Why a mid-cycle upgrade keeps the anniversary date and pro-rates instead of starting a new billing month

Upgrading a subscription mid-cycle does not reset the billing month. The anniversary date is preserved and the upgrade is pro-rated through to the next anniversary. This holds because the upgrade is applied to the existing subscription: when you send a create subscription for the new plan using the same external_id, Lago recognizes the match and treats it as an upgrade rather than a new subscription, so the original anniversary day carries over instead of restarting from the upgrade date.

How it is billed

On a mid-cycle upgrade, Lago immediately invoices the prorated portion of the old plan (the days before the upgrade), then at the end of the period invoices the prorated portion of the new plan (the upgrade date to the anniversary). Normal full-month cycles follow from the next anniversary.

Free-to-paid is a clean instance: the immediate old-plan invoice is zero since the free days cost nothing, and you are billed for the prorated paid-plan days from the upgrade to the anniversary. The net effect is one short prorated charge bridging the upgrade date to the anniversary, then normal monthly billing.

The one thing this depends on is the same external_id. That match is what makes it an upgrade with the anniversary preserved. A different external_id creates a separate subscription with its own start date and anchor, and you would not get this behavior. So you do not need to explicitly terminate the old plan first; the matching external_id is what drives the upgrade.

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