Add-On Alignment with Annual Base Plans

[Wojtek S]

Hello,

I have a question about aligning add-on subscriptions with annual base plans.

Suppose an annual base subscription starts on 01-01-2025. An invoice is generated, and the customer pays successfully. Later, on June 5, 2025, the customer wants to purchase an add-on product. I would like the add-on subscription to align with the base subscription's annual cycle. Specifically:

• The first add-on subscription period should run from 05-06-2025 to 01-01-2026 (with proration).
• Subsequent billing periods for the add-on should align with the base plan, starting on January 1 of each year.

With my current catalog setup (provided below), I can only align the add-on with the subscription bundle's BCD. For example, when I create the add-on subscription on June 6, the first subscription period is from 05-06-2025 to 01-06-2026, aligned to the base plan's BCD (the 1st of the month). This behaviour would be great for a monthly subscription, but is not ideal for an annual plan.

Is there a way to configure my desired add-on alignment logic?

For context, I'm using kbVersion 0.24.12.

Thank you for your help!
Best regards,
Wojtek

My current catalog:

<catalog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="CatalogSchema.xsd">

    <effectiveDate>2025-01-01T00:00:00+00:00</effectiveDate>
    <catalogName>testCatalog</catalogName>

    <recurringBillingMode>IN_ADVANCE</recurringBillingMode>

    <currencies>
        <currency>USD</currency>
    </currencies>

    <products>
        <product name="BASE-PRODUCT">
            <category>BASE</category>
            <available>
                <addonProduct>ADDON-PRODUCT</addonProduct>
            </available>
        </product>
        <product name="ADDON-PRODUCT">
            <category>ADD_ON</category>
        </product>
    </products>
    <rules>
        <changePolicy>
            <changePolicyCase>
                <policy>IMMEDIATE</policy>
            </changePolicyCase>
        </changePolicy>
        <changeAlignment>
            <changeAlignmentCase>
                <toProductCategory>ADD_ON</toProductCategory>
                <alignment>START_OF_BUNDLE</alignment>
            </changeAlignmentCase>
            <changeAlignmentCase>
                <alignment>START_OF_SUBSCRIPTION</alignment>
            </changeAlignmentCase>
        </changeAlignment>
        <cancelPolicy>
            <cancelPolicyCase>
                <policy>END_OF_TERM</policy>
            </cancelPolicyCase>
        </cancelPolicy>
        <createAlignment>
            <createAlignmentCase>
                <alignment>START_OF_SUBSCRIPTION</alignment>
            </createAlignmentCase>
        </createAlignment>
        <billingAlignment>
            <billingAlignmentCase>
                <productCategory>ADD_ON</productCategory>
                <alignment>BUNDLE</alignment>
            </billingAlignmentCase>
            <billingAlignmentCase>
                <alignment>SUBSCRIPTION</alignment>
            </billingAlignmentCase>
        </billingAlignment>
        <priceList>
            <priceListCase>
                <toPriceList>DEFAULT</toPriceList>
            </priceListCase>
        </priceList>
    </rules>

    <plans>
        <plan name="base-product-annual">
            <product>BASE-PRODUCT</product>
            <finalPhase type="EVERGREEN">
                <duration>
                    <unit>UNLIMITED</unit>
                </duration>
                <recurring>
                    <billingPeriod>ANNUAL</billingPeriod>
                    <recurringPrice>
                        <price>
                            <currency>USD</currency>
                            <value>1000.00</value>
                        </price>
                    </recurringPrice>
                </recurring>
            </finalPhase>
        </plan>

        <plan name="addon-product-annual">
            <product>ADDON-PRODUCT</product>
            <finalPhase type="EVERGREEN">
                <duration>
                    <unit>UNLIMITED</unit>
                </duration>
                <recurring>
                    <billingPeriod>ANNUAL</billingPeriod>
                    <recurringPrice>
                        <price>
                            <currency>USD</currency>
                            <value>300.00</value>
                        </price>
                    </recurringPrice>
                </recurring>
            </finalPhase>
        </plan>
    </plans>
    <priceLists>
        <defaultPriceList name="DEFAULT">
            <plans>
                <plan>base-product-annual</plan>
                <plan>addon-product-annual</plan>
            </plans>
        </defaultPriceList>
    </priceLists>
</catalog>

[Shaun Forgie]

HI Wojtek,

Each plan can have its own billing cycle specified in the billing catalog independently of the parent plan in which it is defined as an included or extra add-on. You will have to wait until the next billing cycle date of the parent in order to receive income from the child plan. Even if the child plan had a monthly cycle this would create separate invoice items for each month...that would appear on the annual invoice created by the parent plan. The billing alignment rules in this case are controlling how many invoice items the child plan generates on the parent invoice. It is the parent bundle that actually triggers invoice production.

If you want to get paid immediately upon the child plan being created you will need to define a separate base plan in the catalog and create a subscription from that. This will result in separate invoices / payment transactions for each subscription.

If you wanted to align the subscriptions with the account to consolidate all subscriptions into a single account level invoice you would need to have monthly billing cycles for each plan as the account BCD is a day of month value and only works on a monthly cycle for consolidated invoice generation.

So in summary it's the parent bundle that triggers invoice generation. If you are not using monthly cycles it is the parent bundle that controls the timing of invoice production / payment processing.

Rgs

Shaun

--
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/f093be34-1dc0-4e4a-9252-1b58d1ec6e2cn%40googlegroups.com.

--

Shaun Forgie [Principal] - Method Maker Ltd
57a McIntyre Rd, Manukau 2022, Auckland, New Zealand
Mobile +64 21 666 910 https://www.linkedin.com/in/shaunforgie/

[Reshma Bidikar]

Hello Wojtek,

Just to provide additional information, we have a ticket corresponding to the scenario you've described. See https://github.com/killbill/killbill/issues/1881. 

Regards,

Reshma

[Wojtek S]

Thank you for clarifying things. I appreciate your help.

Best regards,
Wojtek