How Kill Bill Handles Coupons, Discounts, and Price Overrides

by | Dec 21, 2022 | Billing Systems, Features, Pricing, Subscriptions

array of coupons, discounts, free trials, BOGO

The holidays can put quite the squeeze on one’s wallet, what with buying gifts, traveling, and entertaining friends and family. It’s a natural time of the year to offer your customers a lower price like coupons or discounts on your service or product, and Kill Bill can help you do that.

As a business, you have several different ways you can offer savings. For example, you can offer coupons with reduced prices or run campaigns with free trial periods.

That’s straightforward, but the real question is, how does Kill Bill handle discounts, coupons, and trials periods? That’s what this blog post is going to tell you!

Some Background Info About the Catalog, Products, and Plans

If you’re not very familiar with Kill Bill, it’s very helpful to understand our subscription terminology billing terminology:

Catalog

In Kill Bill, the catalog is where you define your products (or services) that the customer can purchase (or rent/lease). For example, a streaming movie service is a product in the Kill Bill catalog.

Plans

The plans in the catalog define the terms for using the product (in this case, the streaming movie service). For example, you could have a free plan limited to two hours of streaming and a basic plan with 10 hours of streaming. 

Phases

Within a plan, you can have different phases. A phase can last a certain amount of time or be unlimited, and it lets you define other information like pricing and billing period (weekly, monthly, etc.). 

Subscriptions

When a customer wants to purchase your product or service, Kill Bill creates a subscription associated with a plan, a customer account, and a start date. 

For more information, see the Catalog section in the Subscription guide and Glossary.

Discounts Via the Catalog

The trial phase, the discount phase, and price lists are ways to offer the customer the use of the product at a discounted rate or for free. 

Trial Phase in the Catalog 

In the catalog, creating a trial phase for a plan lets you define the amount of time a customer can get the product free of charge. A trial phase can be any number of days, months, or even years. (A phase can also be unlimited, but we don’t think you’ll want to do that!) 

Catalog Example: 

<plans>
    <plan name="standard-monthly">
        <product>Standard</product>
        <initialPhases>
            <phase type="TRIAL">
                <duration
                   <unit>MONTH</unit>
                   <number>1</number>
                </duration>
                <billingPeriod>NO_BILLING_PERIOD</billingPeriod>
                <fixedPrice> <!-- empty price implies $0 -->
                </fixedPrice>
            </phase>
        </initialPhases>
        <finalPhase type="EVERGREEN">
               <duration>
                    <unit>UNLIMITED</unit>
               </duration>
               <billingPeriod>MONTHLY</billingPeriod>
               <recurringPrice>
                  <price>
                    <currency>USD</currency>
                        <value>100.00</value>
                   </price>
               </recurringPrice>
        </finalPhase>
</plans>

Discount Phase in the Catalog

You can give customers a certain amount off of the regular price by adding a discount phase to the plan in the catalog. The discount phase defines the discounted price, and it can last for days, months, years (or be unlimited).  

Catalog Example

<plan name="standard-monthly">
    <product>Standard</product>
    <initialPhases>
        <phase type="DISCOUNT">
            <duration>
                <unit>MONTHS</unit>
                <number>1</number>
            </duration>
            <billingPeriod>MONTHLY</billingPeriod>
            <recurringPrice>
                <price>
                    <currency>USD</currency>
                    <value>75.00</value>
                </price>
            </recurringPrice>
        </phase>
    </initialPhases>
    <finalPhase type="EVERGREEN">
        <duration>
            <unit>UNLIMITED</unit>
        </duration>
        <billingPeriod>MONTHLY</billingPeriod>
        <recurringPrice>
            <price>
                <currency>USD</currency>
                <value>100.00</value>
            </price>
        </recurringPrice>
    </finalPhase>
</plan>

When the time period for the trial or discount phase expires, Kill Bill transitions the customer to the next phase in the catalog. In the examples above, it’s the EVERGREEN phase with regular pricing.

Price Lists in the Catalog 

A price list in the Kill Bill catalog is simply a way to identify the same discount pricing (or trial period) for a set of plans. In the catalog, unless otherwise defined, the prices for your plans are a part of the “default” price list. But you can create a price list to handle your business’s special pricing, whether it’s for VIPs, new customers only, or seasonal campaigns. 

Catalog Example

<priceLists>
    <defaultPriceList name="DEFAULT">
        <plans>
            <plan>standard-monthly</plan>
            <plan>sports-monthly</plan>
            <plan>super-monthly</plan>
        </plans>
    </defaultPriceList>
    <childPriceList name="VIP">
        <plans>
            <plan>VIP-standard-monthly</plan>
            <plan>VIP-sports-monthly</plan>
            <plan>VIP-super-monthly</plan>
        </plans>
    </childPriceList>
</priceLists>

Using the above VIP example, the catalog includes three VIP plans that are identical to the regular plans, except for the additional discount (and/or trial) phase. The catalog example below is an example of one such VIP plan with a free trial phase plus a discounted phase.

Catalog Example

<plan name="VIP-standard-monthly">
    <product>Standard</product>
    <initialPhases>
             <phase type="TRIAL">
                 <duration>
                     <unit>DAYS</unit>
                     <number>30</number>
                 </duration>
                 <billingPeriod>NO_BILLING_PERIOD</billingPeriod>
                 <fixedPrice> <!-- empty price implies $0 -->
                 </fixedPrice>
             </phase>
             <phase type="DISCOUNT">
                 <duration>
                    <unit>DAYS</unit>
                    <number>30</number>
                 </duration>
                 <billingPeriod>MONTHLY</billingPeriod>
                 <recurringPrice>
                    <price>
                        <currency>USD</currency>
                        <value>50.00</value>
                    </price>
                 </recurringPrice>
             </phase>
    </initialPhases>
    <finalPhase type="EVERGREEN">
        <duration>
            <unit>UNLIMITED</unit>
        </duration>
        <billingPeriod>MONTHLY</billingPeriod>
        <recurringPrice>
            <price>
                <currency>USD</currency>
                <value>100.00</value>
            </price>
        </recurringPrice>
    </finalPhase>
</plan>

But let’s say you wanted to give the VIPs a perpetually lower price. How do you handle that in the catalog? In that case, you don’t need a trial or discount phase; just define the lower price in the evergreen-unlimited phase. 

Using price lists allows you to leave your default pricing intact and have a specific place in the catalog to tweak the special pricing, which helps to prevent introducing pricing errors.

Additionally, price lists allow you to take advantage of the catalog rules, which you’ll need to define how to handle it when a customer wants to change from a discounted plan to another plan. For example, when a customer upgrades or downgrades, does she still receive the same discount, or does she return to the default price for the plan? If the former, it’s considered a “sticky” price list. If the latter, it’s a “non-sticky” price list. (For more information on this concept, see the Subscription guide.)

Use Price Overrides

Another way to give discounts is with the priceOverrides attribute. You can use this to override the catalog price when Kill Bill is creating (or changing) a subscription (Subscription API). 

Entitlement/Coupon Plugin

An entitlement/coupon type of plugin is called from the core entitlement system and provides a way to intercept subscription operations (e.g., creation, cancellation) and inject your own subscription business logic. Perfect to achieve fully-fledged coupon functionality. Our coupon plugin demonstrates how you can get started with this.  

That wraps it up for December! We hope you have a safe, healthy, and fun holiday season (with lots of great discounts on those gifts you need to buy)!

Related Articles