A Subscription Product Catalog That’s Future-Proof

by | Aug 13, 2021 | Billing Systems, Catalog, Subscriptions

future proof street signs

This is Part 2 in a three-part series about the subscription product catalog. (Here you can read Part 1 and Part 3.)

Last month our blog post covered the foundation for a flexible subscription product catalog. If you missed it or want to refresh your memory, you can read it here: The Foundations of a Flexible Subscription Product Catalog

This month we’re building on the aforementioned catalog foundation. (See what we did there?) We want to discuss the scenarios commonly needed by so many subscription businesses: upgrades, downgrades, and cancellations. 

Naturally, we’ll be referring to the Kill Bill catalog, but we hope this helps those designing their own subscription product catalog architecture or evaluating existing ones.

Subscription Changes Can Get Complicated

One of the main benefits for customers in subscribing to a plan is its inherent flexibility. So, of course they are going to make changes to their plan! They’ll want to upgrade to a plan with more features, downgrade to a less expensive plan, or even cancel their subscription. 

Obviously, your business must first establish its policies regarding upgrades, downgrades, cancellations, and so forth. After that, it must automate the implementation of these policies as much as possible. A sophisticated subscription product catalog gives you the ability to implement your business logic for these situations. 

If your billing system can’t capture the business logic around upgrades, downgrades, and cancellations, the logic ends up in multiple places like the purchase flow, admin UI, and manual processes. The result is a Frankenstein billing system that’s difficult to tweak, can’t scale, and breaks (often!).

An Example: Aligning Subscriptions in the Subscription Product Catalog

A customer adds a plan to their existing subscription. Both plans have multiple phases (trial, discount, etc.). How do you align the phases?

Caroline is on the Basic plan, which is billed monthly. In the middle of the billing cycle, she upgrades to a more expensive annual plan.

By default, new customers subscribing straight to the annual plan have a 30-day trial period. (With Kill Bill, you can define discount/trial periods within a plan by defining them as a plan phases. We covered this in last month’s blog post.)

But Caroline is an existing customer, not a new one. What should the behavior be for customers upgrading from the monthly to the annual plan? 

For example, Caroline could receive the 30-day trial because she was on the Basic plan. Or, because she was already on the Basic plan, she will skip the trial period.  

It’s this type of logic that you can embed in the Kill Bill catalog. No other billing solution vendor has that capability. 

You don’t have to code these business decisions into your billing system. You don’t have to ask your customer service people to remember these policies and adjust for it in the system manually. Once configured, Kill Bill handles it automatically.

Another Example: Aligning Billing in the Subscription Product Catalog

A customer wants to upgrade. When do you apply the change—immediately or at the end of the billing cycle? 

Jerome is currently subscribed to a plan for $10 per month, billed monthly and in advance. In the middle of the month, he upgrades to a $50-per-month plan. 

A business has two options: 

  • Immediately put the change into effect:
    • Give Jerome a $5 credit (which settles up the $10-per-month plan) 
    • Generate an invoice for $25 (which bills Jerome the remaining half of the $50-per-month plan) 
    • Apply the $5 credit to the amount due of $25 for a total amount due of $20.


  • Wait until the end of the billing cycle, and generate an invoice for $50. 

Obviously, the first option is more complicated. But no worries, Kill Bill can handle it, and automatically, too! 

The choice to invoice the customer in the middle of the month would be part of the business’s overall subscription billing policy. If the business decides to change that policy at a later date, it’s a relatively simple change to the Kill Bill catalog. This isn’t true for other billing solution vendors and certainly not the case if you had hard-coded this logic into a home-grown billing system.

Sort It Out with Catalog Rules

In order for Kill Bill to figure out what to do in upgrade/downgrade/cancel situations, it compares the current scenario (a.k.a. context) to a series of catalog rules. 

Kill Bill has two different types of catalog rules: 

  • Subscription alignment rulesHow the subscription is handled when the customer upgrades, downgrades, or cancels.
  • Billing alignment rulesHow to determine the billing date when the subscription changes or multiple subscriptions are part of a customer account. 

Let’s look at one of these rules as an example. This rule defines what happens when a subscription changes, if the change occurs immediately or at the end of the billing cycle

Case Evaluate (True/False) If True, Apply Result
1 The plan is in the Trial phase Change takes place immediately
2 The plan is in the Evergreen phase AND is moving from the Basic to Boutique plan Change takes place at the end of the cycle
3 Neither #1 or #2 apply Change takes place at the end of the cycle


Kill Bill steps through each case beginning with #1, evaluating the current context of the plan against the statement (“Evaluate” column). For the first case in which the statement matches the context, Kill Bill applies the result. 

Wrapping it up…

Kill Bill catalog rules are configured in XML. You can see some catalog samples on GitHub

The Kill Bill catalog editing tool has built-in validation to help write and maintain XML catalogs. That’s available on cloud.killbill.io

In fact, at cloud.killbill.io you can evaluate Kill Bill for free by spinning up your own tenant and playing around in the sandbox. Details are covered in this blog post.

If you have any questions about Kill Bill, let us know or stop by the Kill Bill Community and ask!

Related Articles