Killbill approach for car rental use case (not SpyCar :-)

[Alex]

Hi!
I am currently in the process of evaluating billing systems. Killbill sounds very promising to me. I like the architecture and the concepts around it. It even runs on Docker :-) I’ve been playing around with a local installation and I’ve read a lot of the documentation and mailing-list posts.

Nevertheless I think I need some advice regarding the concepts of Killbill and the best approach to solve the business requirements:
Business scenario: a more or less “standard” car rental setup (yes – I read the SpyCar example :-)

- rental car business where customers can rent vehicles between 1 and 30 days. The duration is specified by the customer when the booking is made
- Customers can add insurance to a booking, standard rate per day
- While the booking is active the customer can extend it, e.g. adding an extra day.
- the longer the booking, the lower the price per day (e.g. 1 day: 100$, 2 days: 175$, etc)
- After returning the car, the customer can be charged for gas (if not returned full), for exceeded mileage or for damages – this will be a second invoice
- Before booking we want to show the customer the costs as they will appear on the invoice, incl. Tax (e.g. a shopping cart)
- On the invoice we want to show taxes per invoice item, the tax rate may differ depending on the country
- Bookings can be discounted, e.g. by adding a coupon
- The billing/invoicing/payment system shall
-- Create and ship invoices
-- collect money
-- Manage the dunning process
-- Create accounting reports
-- Store pricing information if possible

Questions:
- Are subscriptions and catalogs the right approach to set
the system up with killbill? Especially as a booking is not really a subscription but rather a one-time transaction. How would you approach this issue using killbill?
- How would you handle discounts? Can Discounts on invoice or invoice item be implemented using Plugins?
- Is it possible to calculate taxes per invoice item using a taxation plugin?
- How would you handle extra costs such as Gas or mileage? (e.g. Usage based billing, Add-ons?)
- Is there a way to have killbill calculate the invoice before a booking is made, e.g. for displaying a shopping cart?

Your help is very much appreciated!

Cheers,
Alex

[Pierre-Alexandre Meyer]

Hi Alex,

There is a lot to cover. Let me answer your questions at a high level and then we can iterate on it.

On Tue, Feb 3, 2015 at 11:16 AM, Alex <kraus...@gmail.com> wrote:

- Are subscriptions and catalogs the right approach to set the system up with killbill? Especially as a booking is not really a subscription but rather a one-time transaction. How would you approach this issue using killbill?

You have several options. Either setup fixed-length plans (non-evergreen, up to 30 days) or bypass the subscription system entirely (Kill Bill provides pure invoicing and even pure payments APIs). I've never tried the former, but it should be supported. If not, we can fix it ;-)

- How would you handle discounts? Can Discounts on invoice or invoice item be implemented using Plugins?

Yes, coupon logic should be implemented in plugins. We offer APIs to either item adjust and/or apply credits to accounts and/or invoices.

- Is it possible to calculate taxes per invoice item using a taxation plugin?

Yes, similarly tax should be done in plugins. Usually, you would integrate with a third-party (e.g. Avalara) but you could do it yourself. We have an example in Ruby here: https://github.com/killbill/killbill-invoice-test-plugin/blob/master/lib/invoice_test/api.rb

 

- How would you handle extra costs such as Gas or mileage? (e.g. Usage based billing, Add-ons?)

It looks like usage would be a fit (so you can bill in arrear).

 

- Is there a way to have killbill calculate the invoice before a booking is made, e.g. for displaying a shopping cart?

If you are going to use the catalog and subscriptions, yes, there is a dry run API. If you are using the pure invoice APIs (i.e. creating charges manually), the invoice is kept open until you explicitly trigger a payment for it (which could happen at the end of the checkout flow).

I would suggest starting prototyping, to see which integration path would work better.

Hope that helps!

--

Pierre

[Alex]

Hi Pierre,
thank you very much for your quick reply which helps me a lot. It points me in the right direction! I'll definitely do some prototyping to find out the best approach. There will probably be more questions :-)

regarding this point:

> You have several options. Either setup fixed-length plans (non-evergreen, up to 30 days) or bypass the subscription system entirely (Kill Bill provides pure invoicing and even pure payments APIs). I've never tried the former, but it should be supported. If not, we can fix it ;-)

I put together an example catalog xml:
- a car category as product, as well as gas as usage based product
- 2 plans with different durations, not evergreen but fixedterm
-1 plan for gas, usage based

Question: do I have to define a product entry for each plan duration? or can several plans with different durations point to the same product (tried it, but doesn't validate).

Thank you very much in advance!
Alex


XML:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<catalog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="CatalogSchema.xsd ">

<effectiveDate>2013-02-08T00:00:00+00:00</effectiveDate>
<catalogName>Titos Rental</catalogName>

<recurringBillingMode>IN_ARREAR</recurringBillingMode>

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

<units>
<unit name="gallons"/>
</units>


<products>
<product name="cat_compact_1">
<category>BASE</category>
<available>
<addonProduct>Gas</addonProduct>
</available>
</product>
<product name="cat_compact_2">
<category>BASE</category>
<available>
<addonProduct>Gas</addonProduct>
</available>
</product>
<product name="Gas">
<category>ADD_ON</category>
</product>
</products>

<rules>
<cancelPolicy>
<cancelPolicyCase>
<productCategory>BASE</productCategory>
<policy>END_OF_TERM</policy>
</cancelPolicyCase>
<cancelPolicyCase>
<productCategory>ADD_ON</productCategory>
<policy>IMMEDIATE</policy>
</cancelPolicyCase>
<cancelPolicyCase>
<policy>END_OF_TERM</policy>
</cancelPolicyCase>
</cancelPolicy>
<createAlignment>
<createAlignmentCase>
<alignment>START_OF_BUNDLE</alignment>
</createAlignmentCase>
</createAlignment>
<billingAlignment>
<billingAlignmentCase>
<alignment>ACCOUNT</alignment>
</billingAlignmentCase>
</billingAlignment>
</rules>

<plans>
<plan name="cat_compact_plan_1">
<product>cat_compact_1</product>
<finalPhase type="FIXEDTERM">
<duration>
<unit>DAYS</unit>
<number>1</number>
</duration>
<fixed>
<fixedPrice>
<price>
<currency>USD</currency>
<value>100.00</value>
</price>
</fixedPrice>
</fixed>
</finalPhase>
</plan>

<plan name="cat_compact_plan_2">
<product>cat_compact_2</product>
<finalPhase type="FIXEDTERM">
<duration>
<unit>DAYS</unit>
<number>2</number>
</duration>
<fixed>
<fixedPrice>
<price>
<currency>USD</currency>
<value>175.00</value>
</price>
</fixedPrice>
</fixed>
</finalPhase>
</plan>

<plan name="gas">
<product>Gas</product>
<finalPhase type="FIXEDTERM">
<duration>
<unit>DAYS</unit>
</duration>
<usages>
<usage name="gas-monthly-in-arrear" billingMode="IN_ARREAR" usageType="CONSUMABLE">
<billingPeriod>NO_BILLING_PERIOD</billingPeriod>
<tiers>
<tier>
<blocks>
<tieredBlock>
<unit>gallons</unit>
<size>1</size>
<prices>
<price>
<currency>USD</currency>
<value>3.95</value>
</price>
</prices>
<max>100</max>
</tieredBlock>
</blocks>
</tier>
</tiers>
</usage>
</usages>
</finalPhase>
</plan>
</plans>
<priceLists>
<defaultPriceList name="DEFAULT">
<plans>
<plan>cat_compact_plan_1</plan>
<plan>cat_compact_plan_2</plan>
<plan>gas</plan>
</plans>
</defaultPriceList>
</priceLists>
</catalog>

[Pierre-Alexandre Meyer]

On Wed, Feb 4, 2015 at 3:35 AM, Alex <kraus...@gmail.com> wrote:

Question: do I have to define a product entry for each plan duration? or can several plans with different durations point to the same product (tried it, but doesn't validate).

You can define different plans for the same product but with different phase types/length. Just make sure the plan name is unique across the catalog.

What did you try that doesn't validate (your catalog looks good so far)?

--

Pierre

[Alex]

Hi Pierre,
thank you for your reply!

if you take the catalog xml example I posted above have both non-usage plans (cat_compact_plan_1 and cat_compact_plan_2) pointing to the same product (e.g. cat_compact_1) I get the following message when validating with killbill-catalog-0.13.1-load-tool.jar

"There are 2 plans in pricelist DEFAULT and have the same product/billingPeriod (cat_compact_1, NO_BILLING_PERIOD)"

So having 2 plans pointing to the same product with only differing durations obviously does not work. How would you set this scenario up? Like having 1 product with a different plan depending on the duration of the subscriptions.

Thank you for your help!
Alex

[Pierre-Alexandre Meyer]

On Mon, Feb 9, 2015 at 8:19 AM, Alex <kraus...@gmail.com> wrote:

So having 2 plans pointing to the same product with only differing durations obviously does not work.

Ah, indeed! This looks like a limitation, I've opened https://github.com/killbill/killbill/issues/271 for tracking.

How would you set this scenario up? Like having 1 product with a different plan depending on the duration of the subscriptions.

Yes, you need to create multiple products as a workaround for now.

--

Pierre

[kraus...@gmail.com]

Thank you for the clarification!
I'll probably be back with more questions soon ;-)

Alex