Kill Bill demo

The demo runs on AWS and is composed of the following components:

The system has been configured with multiple tenants, but for the purpose of that demo, we only care about the demo tenant. The system has also been configured with different credentials (having access to some or all tenants), and having each a set of specific permissions.

We only share with the rest of the world a read-only set of credential for the demo tenant, which means that any actions changing the state of that system will trigger a 401 Unauthorized response from the server. Note that KAUI also understands permissions and usually hides the links for which a given user cannot access, but we thought it would be more interesting to show the existing actions, even though the user does not have the correct rights.

The data has been generated using some scripts and is based on a cloud catalog. The idea behind the Cloud catalog is to simulate a SAAS service similar to AWS, where customers can pay for servers.

The users have the choices to either be billed purely based on their usage, or to reserve instances (recurring subscriptions) and then be billed for their usage at a lower price. The usage billing happen in arrear at the end of each month, and the recurring subscriptions for the reserved instance happens in advance at the beginning of the period.

The following plans are available from this catalog:

In addition the catalog also adds an ADD_ON product that is included by default with all the '-metal-' plans and can be purchase in addition for the '-vm-' plans.

Finally, in order to keep things simple, we are only billing based on unit cpu-hour.

The catalog is available across 5 different currencies (USD, GBP, EUR, JPY, BTC).

The first thing to mention is that each Account in the system is created with a specific timezone that will drive all conversions from a well defined point of time to a local date (with no time). For more details around date and time in Kill Bill, please refer to this blog. KAUI will display for each account the dates (with no time) in the account timezone.

The following accounts were created in different parts of the world to show the effect of the timezone. Their subscriptions was all created at approximately the same time (point of time, independent of timezone), and yet because they are in different parts of the world, the local dates and date at which they get billed will end up being different:

The subscriptions for all 3 accounts were created on 2015-08-01T01:00:00.000Z. The accounts were created without specifying the BCD (BillCycleDay, or date at which the account would get billed in the month) and so the system computed the BCD based on when the first subscription was created, which is 2015-08-01T01:00:00.000Z. Therefore both Brian King and Yokuri Matsumoto will end up with a BCD of 1 and John Silver will end up with a BCD of 31 (the date in the month in his timezone where that first subscription was created). Both Brian and Yokuri will be billed on the first of the month, and John will be billed at the end of each month.

Each product in the catalog can be defined with a specific Billing Alignment to control which subscriptions should be invoiced together.

We created an account Pierre Quiroule where we created 2 subscriptions, one MONTHLY and one ANNUAL.

The catalog can be configured using billing alignment sections to decide whether subscriptions should be billed independently (at different dates) or whether they should be grouped on a specific invoice. In that scenario, if all subscriptions were aligned at the ACCOUNT level, they would all be billed on the 1st of the month (default BCD chosen by the system based on when the first subscription was created). When the ANNUAL subscription gets created, the system would then pro-rate the ANNUAL to realign with the 1st of the month, and the customer would not necessarily understand why he does not pay for a full year. So in order to avoid that, we specified a SUBSCRIPTION level billing alignment for all the ANNUAL subscriptions.

Each subscription is created based on a Plan definition from the catalog. The Plan definition may contain several PlanPhases to define things like 14 days trial period, or a discounted period, …​ Subscriptions can be grouped together in a SubscriptionBundle to provide some global control on the group, such as the ability to pause, cancel the whole group, …​

So, because we can have groups of subscriptions, and because each subscription goes through phases (trial, discount, evergreen, …​), there is a need to define how things align with each other:

Mathew Brown first subscribes to a reserved-vm-monthly-trial-bp on 2015-08-01. That subscription has a 14 days trial phase, which will expire on 2015-08-15. 5 days later, Mathew Brown decides to purchase the add-on backup-daily-monthly-trial-bp which also has a 14 days trial phase. As a merchant we decided that when the trial period for the base subscription would expire, any add-on trial phase would also expire at the same time. The way to achieve that, is to configure the catalog with a START_OF_BUNDLE PlanAlignmentCreate.

Looking at the invoices and the timeline from Mathew Brown, you can verify that the add-on trial period for both subscriptions ended on 2015-08-15 although the second subscription started on 2015-08-06 and also had a 14 days trial period.

The system offers some policies to cancel subscriptions and define the behavior of when the cancelation of the service occurs (entitlement level), and when the cancelation of the billing occurs (subscription level in our Kill Bill terminology). Those policies can be defined at the catalog level, or overridden on a per call basis. The policies are a convenient way to specify to cancel immediately or at the end of the term (that is up to when the subscription was purchased for in-advance billing mode).

In this example we will only focus on the effect of the billing policies:

Refund operations are tied to previous purchase operations (auth + capture) and are therefore solely related to payments (and not invoices). However, each invoice has a balance which is computed by summing all the invoice item amounts (positive for when they are to be paid and negative for credits) and for which payment amounts are subtracted; a payment amount is itself defined as the sum of the purchase amounts minus the refund amounts. So, a refund operation will not change the invoice itself but it will affect the balance of that invoice.

Jean-Baptiste Poquelin and Agostino Giordano will both create a subscription, get invoiced, pay their invoice and later call customer service to get a refund:

Sean Connery decides to subscribe to the cloud service, and because he knows he is a heavy user, he decides to purchase the reserved instances, where one gets billed on a recurring basis (whether servers get used or not), and then gets billed for usage at a lower rate.

James Bond on the other hand, is not sure about that cloud service provider, and decides to go for a pure usage model by purchasing the on-demand-metal product.

Looking at James Bond’s invoices, you can verify he only gets billed for his usage. Sean Connery’s however is invoiced in-advance for the recurring subscription part and in-arrear of the usage piece.