Subscription Product Catalog: Versioning, Price Changes, and Pricing Overrides

by | Sep 14, 2021 | Catalog, Pricing, Subscriptions

Color-coded catalog

This is the final blog post in a three-part series about the subscription product catalog. Here’s what we covered in the previous two blog posts: 

  • In Part 1, we went over the basics: 
    • Products
    • Plans
    • Plan phases
    • Price lists
  • In Part 2, we discussed how to handle subscription changes (like upgrades, downgrades, and cancellations) using subscription alignment rules and billing alignment rules

For Part 3, we’ll touch on some catalog topics that, when implemented properly, help track product changes and keep your product team sane:  

  • Catalog versions
  • Deferred price changes
  • Price overrides

We’ll also discuss how it’s possible to use Kill Bill without even using the catalog subsystem. Yep… we have customers who use the subscription billing and payment side of Kill Bill, but prefer to use their own catalog. Make sure to stick around for that!

By the way, we’ll be referring to the Kill Bill catalog because that’s what we know best. Whether you’re interested in Kill Bill, designing your own subscription product catalog architecture, or evaluating existing subscription billing systems, we hope this blog post helps!

Keep Catalog Versioning Simple

Obviously, when you’re running a subscription business, your product team is going to want to make changes. They’ll need to add new products, change prices, modify plans, and so forth. The subscription product catalog you use should support these tasks as well as track previous catalog versions. 

As mentioned in Part 2, the Kill Bill catalog is configured as an XML file. To manage versions, you’ll have one XML catalog for each version. Kill Bill ranks the catalog XML files based on their effective date, with each catalog superseded by the next. 

The effective date on the subscription product catalog is especially important when the system needs to determine which version of the catalog to use for a customer’s subscription. For example, when Kill Bill creates a new subscription for a customer (or when the customer switches from one plan to another), it uses the plan price from the most recent version of the catalog. That makes sense because you want to use up-to-date pricing information. 

Time goes by, and it’s time to invoice that customer. Kill Bill retrieves the plan price from the same version of the catalog that was used when it created the subscription (or switched the customer from one plan to another). That also makes sense because you want to invoice the customer at the same price for which they signed up (otherwise, they get pretty cranky).

The ability to reference previous catalog versions is also important if you remove a plan. In that scenario, it’s likely that you would want existing subscriptions to be able to refer to it, but it would not be available to future subscribers. And that’s exactly what Kill Bill does.

Defer Price Changes for Existing Subscriptions

While we’re on the topic of catalog changes, let’s say you want to raise the price for a particular plan. You want the new, higher price to apply to new subscribers, but for existing subscriptions, you want to ease them into the higher price at a later time. 

Within the Kill Bill catalog, you can configure a special effective date at the plan level. That effective date applies only to existing subscriptions.

When you define that special effective date (hmm… let’s call it effectiveDateForExistingSubscriptions), voilà! For new subscriptions to the plan, the higher price is immediately effective, but for existing subscriptions, it’s effective only after that special effective date.

Override Prices at the Subscription Level

Some businesses need the ability to apply a price override at the subscription level. You can do this in Kill Bill with the priceOverrides attribute, used when creating or updating a subscription. The price override applies only to that specific subscription. 


Customer Regular Subscription Price Per Month Price Override Per Subscription







Price overrides that are consistent and or systematic (e.g., first 14 days are discounted 15%) are best handled by defining a discount period at the plan phase level. (We discussed plan phases in Part 1). 

Use Your Own Catalog with Kill Bill 

It’s not unusual for a business to contact us wanting to use Kill Bill for subscription management, invoicing, and payments, but use its own existing catalog system. Via a catalog plugin, you can use Kill Bill with an external catalog system, whether it’s of the home-grown variety or a third-party catalog system. 

Caveat: If the catalog model is too different from Kill Bill’s, it might be too challenging (or even impossible) to interact with Kill Bill.

Read more about how plugins can change Kill Bill’s default behavior in this blog post.

The catalog plugin, once it’s configured for your specific needs, serves two functions:

  • It entirely bypasses the Kill Bill catalog subsystem.
  • It interacts with an existing catalog service to access the catalog information.
  • It serves as a mapping function between the third-party/legacy catalog service abstractions and the Kill Bill catalog abstractions.

In this use case, the catalog functionality is completely delegated to the external catalog system. The external catalog system must be able to handle all of the catalog logic (such as price overrides) without relying on Kill Bill. 

An Example of Using a Dynamic Catalog Database with Kill Bill

MiKashBoks needed a more dynamic catalog solution for their group-based savings and lending social-financial app, so they developed their own catalog plugin. The MikashBoks founder described the experience in this article. We don’t believe the MiKashBoks implementation is live, but it’s a great example of how you can adapt Kill Bill for your business needs, whether you’re a traditional SaaS, ecommerce business, or non-traditional B2C solution like MiKashBoks.

That Wraps It Up!

We hope you enjoyed this three-part series on the subscription product catalog. If you have a specific Kill Bill topic you’d like us to focus on, please let us know

If you’d like to keep in touch, please sign up for our quarterly newsletter. Questions? Ask the Kill Bill Community

Related Articles