Introduction to Kill Bill using a fictitious vignette service

Compared to a commercial solution it’s more difficult to understand the system since there is no direct contact with the supplier. A commercial product would normally come with a guided product demo and probably include the assistance of a solution architect or any other expert, who could help you with any questions you might have. Kill Bill acknowledges this problem and provides you with an amazing subscription guide, where all its features are explained in a car rental example. This is a great starting point to understand the functionalities that Kill Bill offers. At this point, it’s only fair to mention that Kill Bill has an active mailing list and that behind the tool there is a company that offers support. Nevertheless, this article intends to be an addition to the subscription guide. It won’t describe all features Kill Bill provides but rather show the implementation of our example.

The example

Our example is a fictitious vignette service. One that can’t be realized the way we modeled it because of legal issues, but it’s still a relevant example because it is highly influenced by the challenges we’re facing in our customer projects. We came up with this example because one of our offices is located close to the border to Austria and Switzerland. In both countries, you need a vignette to legally drive on their highways.

Our vignette service offers two different plans: Family and Flex. Both are typical examples you’d encounter when you’re dealing with digital services. Therefore, they should be easy to adapt to your use case. The Family plan models a scenario where you need a base subscription to purchase specific items or close constitutive contracts. In our specific case, you need the base subscription to purchase one or both vignettes. Those vignettes also have their own duration. This is a scenario we encounter a lot with customers who transform from the transactional business to subscriptions. This is why we used the original prices and duration for the respective vignette. The subscription’s value is the possibility to use the purchased vignettes in more than one vehicle within your family. Normally the vignette would be limited for use in one vehicle only. The Flex plan offers higher flexibility as you’re able to purchase a vignette just for one day. This causes a higher monthly base fee and the vignette can’t be used in a different vehicle. This is a typical scenario for usage-based billing. It’s more native to subscriptions than the Family plan.

The Family plan

<products>
    <product name="Family">
        <category>BASE</category>
        <available>
            <addonProduct>VignetteAT</addonProduct>
            <addonProduct>VignetteCH</addonProduct>
        </available>
    </product>
    <product name="VignetteAT">
        <category>ADD_ON</category>
    </product>
    <product name="VignetteCH">
        <category>ADD_ON</category>
    </product> 
    … 
</products>

Just to recap: It’s only possible to purchase the vignettes if the customer has a valid base subscription. Kill Bill supports this behavior using so-called ADD_ON products. In the snippet above we see that we’ve created 3 different products:

• Family as a BASE product
• VignetteAT as an ADD_ON product
• VignetteCH as an ADD_ON product

In addition, it’s necessary to add both ADD_ON products to the Family product as available products. Now it’s possible to purchase the vignettes if you have a valid base subscription.

<plans>
    <plan name="family-monthly">
        <product>Family</product>
        <finalPhase type="EVERGREEN">
            <duration>
                <unit>UNLIMITED</unit>
            </duration>
            <recurring>
                <billingPeriod>MONTHLY</billingPeriod>
                <recurringPrice>
                    <price>
                        <currency>EUR</currency>
                        <value>10.00</value>
                    </price>
                </recurringPrice>
            </recurring>
        </finalPhase>
    </plan>
    …
</plans>

Now that the products have been defined, the plans must be specified. As you can probably guess from just looking at the example above, it’s possible to define multiple phases for one plan, however, this isn’t necessary for our example. Therefore we only use the final phase of type EVERGREEN. EVERGREEN means that it’s no special phase. The phase duration is unlimited, it’s billed monthly and the recurring price is 10 €. Pretty easy to understand.

<plans>
    …
    <plan name="family-vignette-at">
        <product>VignetteAT</product>
        <finalPhase type="FIXEDTERM">
            <duration>
                <unit>MONTHS</unit>
                <number>2</number>
            </duration>
            <fixed>
                <fixedPrice>
                    <price>
                        <currency>EUR</currency>
                        <value>28.70</value>
                    </price>
                </fixedPrice>
            </fixed>
        </finalPhase>
    </plan>
    …
</plans>

We also have to define plans for the vignettes themselves. The example above only shows the vignette for Austria, but it’s basically the same for the other vignette as only the values differ. It’s almost the same for the Family plan with the differences that the phase is of type FIXEDTERM and a fixed price is used instead of a recurring price.

The Flex plan

<units>
    <unit name="vignette-at"/>
    <unit name="vignette-ch"/>
</units>

First, we declare the units we will use to measure the usages. Then we define the plan.

<plans>
    …
    <plan name="flex-monthly">
        <product>Flex</product>
        <finalPhase type="EVERGREEN">
            <duration>
                <unit>UNLIMITED</unit>
            </duration>
            <recurring>
                <billingPeriod>MONTHLY</billingPeriod>
                <recurringPrice>
                    <price>
                        <currency>EUR</currency>
                        <value>20.00</value>
                    </price>
                </recurringPrice>
            </recurring>
            <usages>
                <usage name="flex-monthly-at" billingMode="IN_ARREAR" usageType="CONSUMABLE">
                    <billingPeriod>MONTHLY</billingPeriod>
                    <tiers>
                        <tier>
                            <blocks>
                                <tieredBlock>
                                    <unit>vignette-at</unit>
                                    <size>1</size>
                                    <prices>
                                        <price>
                                            <currency>EUR</currency>
                                            <value>1.5</value>
                                        </price>
                                    </prices>
                                    <max>-1</max>
                                </tieredBlock>
                            </blocks>
                        </tier>
                    </tiers>
                </usage>
                …
            </usages>
        </finalPhase>
    </plan>
</plans>

The first part of the Flex plan is identical to the Family plan besides the difference in the price. It additionally defines the usages for the vignettes. This means that we don’t have to add additional plans for the vignettes as we did before. Now let’s have a closer look at the definition of the usage for the Austrian vignette. It uses the billing mode IN_ARREAR, which is currently the only supported mode. The mode means that customers are billed based on the usage of the previous period. In our case, the previous month. The usage type CONSUMABLE is described as follows in the subscription guide: “This is used for defining prices that are based on the number of units (of a certain types) being consumed — e.g water consumed in the last period” [1]. Kill Bill can do more complex usage-based billing and our example only uses the basic functionality.

Open Points

We still have one open point with the vignettes you can buy in the Family plan. Let’s use the Austrian vignette to show the problem: The duration of the Austrian vignette is 2 months. During this time, it shouldn’t be possible to buy it again. Unfortunately, we haven’t found a way to realize this behavior. This probably must be checked by the system which calls Kill Bill.

Kill Bill and its catalog convinced us

It was easy to map our plans into Kill Bill. We particularly liked the ease the relationships between the plans can be modeled. Even without a product demo it only took us little effort to reach our desired result.

We hope this article showed you how easy it is to realize your plans with Kill Bill, especially if their complexity is similar to the ones we’ve used in this article. The catalog XML is rather easy to understand, but it also brings the typical XML drawbacks with it. It feels like the more products and plans you have, the more difficult it gets to maintain them. But this is only a guess and not an observation we made. We hope this easy example helps you to get started with Kill Bill. You should really give it a try.

View the full catalog.xml for this example.

Mehr zu Software Development erfahren

List of References:

Kill Bill subscription guide – Usage Billing; https://docs.killbill.io/latest/userguide_subscription.html#components-catalog-usage (accessed 04 May 2021)