Subscription Change Plan - prorate new charge to initial period (endDate)

[Arthur Morgan]

Good morning everyone,

In our product catalog, we have plans that are billed in advance. These plans have unlimited validity and an annual billing period.

I would like to achieve the following scenario:

• I create a subscription on 01/01/2026, and an invoice is generated with a recurring fee covering the period from 01/01/2026 (startDate) to 01/01/2027 (endDate).

• If I perform a plan change on this subscription on 01/06/2026, the system generates:

  • an ADJUSTMENT invoice item to credit back the unused portion of the old plan, and

  • a new invoice item for the recurring fee of the new plan.

However, the recurring fee for the new plan has a startDate of 01/06/2026 and an endDate of 01/06/2027 (i.e., a full annual charge, not prorated).

How can I ensure that the new plan’s recurring fee is prorated, so that its endDate remains aligned with the original subscription cycle (i.e., 01/01/2027), instead of starting a new annual period?

In other words, I would like the new plan to be billed only for the remaining period up to 01/01/2027, rather than triggering a new full-year charge.

I tried to set  billingAlignment with subscription or bundles, but the result remains the same. 

Rules defined in my catalog:

<rules>
                <changePolicy>
                    <changePolicyCase>
                        <policy>END_OF_TERM</policy>
                    </changePolicyCase>
                </changePolicy>
                <changeAlignment/>
                <cancelPolicy>
                    <cancelPolicyCase>
                        <policy>END_OF_TERM</policy>
                    </cancelPolicyCase>
                </cancelPolicy>
                <createAlignment/>
                <billingAlignment>
                    <billingAlignmentCase>
                        <productCategory>ADD_ON</productCategory>
                        <alignment>BUNDLE</alignment>
                    </billingAlignmentCase>
                    <billingAlignmentCase>
                        <alignment>BUNDLE</alignment>
                    </billingAlignmentCase>
                </billingAlignment>
                <priceList>
                    <priceListCase>
                        <toPriceList>DEFAULT</toPriceList>
                    </priceListCase>
                </priceList>
            </rules>

Thanks a lot!!
Arthur 

[karan bansal]

Hi Arthur,

The behavior that you are observing about full charge for the changed plan and date moved to 1 year from the start date of new plan, is the default KB behavior and cannot be modified via catalog rules. 

To achieve the scenario, you can look into invoice plugins that would catch the invoice generated by the core and allow you to make the changes as required.

Regards

Karan

[Harish K]

Hi,

What you are seeing is the default Kill Bill behavior when a plan change happens mid-cycle.
Kill Bill credits the unused portion of the old plan and starts a new billing cycle for the new plan from the change date, which is why you see the new annual charge from 01/06/2026 to 01/06/2027.

If you want the billing cycle to remain aligned with the original subscription cycle (e.g., still ending on 01/01/2027), you need to configure changeAlignment in your catalog.

Instead of leaving it empty:
<changeAlignment/>

define like this :

<changeAlignment>
    <changeAlignmentCase>
        <alignment>START_OF_SUBSCRIPTION</alignment>
    </changeAlignmentCase>
</changeAlignment>

This keeps the billing cycle anchored to the original subscription start date.
When the plan change occurs on 01/06/2026, Kill Bill will then credit the unused portion of the old plan and charge the new plan only for the remaining period up to 01/01/2027.

On Saturday, March 7, 2026 at 12:27:03 PM UTC+5:30 Arthur Morgan wrote:

[Harish K]

Hi,

What you are seeing is the default Kill Bill behavior when a plan change happens mid-cycle.
Kill Bill credits the unused portion of the old plan and starts a new billing cycle for the new plan from the change date, which is why you see the new annual charge from 01/06/2026 to 01/06/2027.

If you want the billing cycle to remain aligned with the original subscription cycle (e.g., still ending on 01/01/2027), you need to configure changeAlignment in your catalog.

Instead of leaving it empty:
<changeAlignment/>

define like this :

<changeAlignment>
    <changeAlignmentCase>
        <alignment>START_OF_SUBSCRIPTION</alignment>
    </changeAlignmentCase>
</changeAlignment>

This keeps the billing cycle anchored to the original subscription start date.

When the plan change occurs on 01/06/2026, Kill Bill will then credit the unused portion of the old plan and charge the new plan only for the remaining period up to 01/01/2027.

--
You received this message because you are subscribed to the Google Groups "Kill Bill users mailing-list" group.
To unsubscribe from this group and stop receiving emails from it, send an email to killbilling-us...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/killbilling-users/880ab5ab-ce67-49b7-9d7f-e91ad9892570n%40googlegroups.com.