We have created a simple demo that can be accessible at https://demo.killbill.io/. The purpose is to demonstrate the power and flexibility of our admin UI (also referred to as KAUI, Kill Bill Admin UI), and also to showcase, through some well constructed accounts, some specific functionalities of the system.
When logging-in with those credentials, KAUI will immediately select the demo tenant, one will be able to play around using the synthetic data we generated for the purpose of that demo.
The demo runs on AWS and is composed of the following components:
An instance of Kill Bill server runs on one EC2 instance
An instance of KAUI runs on one EC2 instance
An instance of RDS (MySQL) serves the databases for both Kill Bill server and KAUI
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.
Catalog and Synthetic Data
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:
on-demand-metal-no-bp: raw hardware with no subscription (pure usage model)
reserved-metal-annual-bp: raw hardware, with a yearly reservation
reserved-metal-monthly-bp: raw hardware, with a monthly reservation
reserved-vm-monthly-bp: VM, with a monthly reservation
reserved-metal-monthly-trial-bp: raw hardware, with a monthly reservation and a 14 days free trial period
reserved-vm-monthly-trial-bp: VM, with a monthly reservation and a 14 days free trial period
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
The catalog is available across 5 different currencies (USD, GBP, EUR, JPY, BTC).
Each of the accounts (along with some subscriptions, usage, invoices, payments) described below was created to showcase some specific features.
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:
Brian Kinglives in London and has a timezone of
John Silverlives in Pago Pago and has a timezone of
Yokuri Matsumotolives in Tokyo and has a timezone of
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
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
2015-08-01a subscription for the plan
reserved-metal-monthly-bpwas created and the system invoiced for the period
5 days later, on
2015-08-06, a new subscription for the plan
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
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
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
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
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:
Allison Greenwichstarts a subscription on
2015-08-01and gets billed for the period of
2015-09-01. Then on
2015-09-01, she gets billed for the next period and on
2015-09-11, she cancels and because the catalog was configured to cancel
END_OF_TERMshe does not get any pro-ration credit for the period of
Christian Lolipopdoes the exact same thing, but instead of canceling through the merchant UI (with the default
END_OF_TERMpolicy), he calls the customer support and complains loud enough to make the rep perform an
IMMEDIATEcancelation (rep can override the policy from KAUI).
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:
In the case of
Jean-Baptiste Poquelin, the rep will do a pure refund operation, giving him his money back, but keeping his invoice unpaid (and potentially he might lose his service by becoming overdue); this could be useful if the customer decides to pay with a different payment instrument for instance.
In the case of
Agostino Giordano, the rep will do a refund operation with item adjustment to make sure the invoice does not show any balance. As a result
Agostino Giordanonot only gets his money back, but he still has has a 0 balance.
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
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.