BlockingState Abstractions

BlockingState Abstractions

In this blog, we will explore the power behind the BlockingState abstraction inside Kill Bill. Overview: The BlockingState events were introduced in version 0.6.x, so while they are certainly not new, they were mostly used for internal purpose inside Kill Bill.  We recently enriched our apis to make them fully available to plugins. Let’s take a simple use case where a user subscribes to a monthly recurring Plan on January 1st 2016 (and catalog was configured to bill in advance). Each 1st of the month, the invoicing system takes as an input the subscription state (subscription events) and the user is billed for a full month. This works quite well, but how can we address the following questions:   Entitlement: The ability to separate what the user is billed for and the service that she receives (e.g if user cancels mid month, we may want to terminate the service right away and keep the billing until the end of the month) Overdue: The user does not pay its bills. We want to allow to introduce some states that will define a gradual degrade of the service until the user pays Pause/Resume: Ability to arbitrarily pause the billing (and/or its associated entitlement) for a period of time. The BlockingState events allow to introduce arbitrary states associated to subscriptions, and allow to modify the behavior of the system to block billing or entitlement periods, solving the original use cases we had and more…   Internals: Before looking at their usage, let’s review what they contain: stateName : A string that is to be interpreted by the service inserting such event blockingStateType : An...
Moving Towards a Flexible Catalog

Moving Towards a Flexible Catalog

Back in the days, when we started the design for Kill Bill, some of the first discussions we had were centered around catalog (definition of products, prices, behavior associated to each product or transition from one product to another, …). We had lots of use cases that we knew about such as providing support for trials and discount, grouping things on one or multiple invoices, providing support for subscription dependencies (add-ons), international support, … Our initial implementation was based on a static set of XML files, where each file represents a specific version of the catalog. XML proved to be a fairly good choice to represent our various abstractions and provide the flexibility we wanted through the use of various catalog rules. However, we also knew that our knowledge was incomplete, but the idea was that, as we would discover new use cases we could enhance our object model. And this statement also happened to be true: when we started to implement some of the usage billing case scenarios, we added new usage sections in our catalog XML and again the XML representation was powerful enough to cover all the use cases we came about. When we moved to fully implement the multi-tenancy feature, we then needed to have each tenant own its catalog. The XML based model was still a good fit. The only difference here, was that the catalog was not something that was shared across tenants any longer, but something that administrators of the various tenants could configure through the use of endpoints. Then, one day, on the mailing list we had a request to support...
Kill Bill 0.14.0 Released!

Kill Bill 0.14.0 Released!

We are excited to announce our new release Kill Bill 0.14.0! The release is mostly targeted to cover all the current use cases identified in our talk , that is: Subscription As A Service Global Payment System Subscription As A Service On the Subscription As A Service side, the following areas have been enhanced: Multi-tenancy. In particular, the ability to upload per tenant config (catalog, invoice templates, invoice translations), and per plugin config (so, for instance the same stripe payment plugin could be used across multiple tenants with different set of credentials, …). Catalog Price Override. Subscriptions APIs have been enhanced to now support overriding static catalog prices, by automatically adding new catalog entries with those new prices. The price override occurs at the phase level, and allows to override both fixed and recurring prices in one or multiple phases of the plan associated with the new subscription. Ability to dynamically add new roles and admin users. We added APIs that allow to add new roles and admin users (without having to restart Kill Bill instances). This is mostly useful for deployments that rely on static shiro.ini configuration files, as opposed to LDAP (which we also provide). New plugins: Tax plugin (Avalara) Email notification plugin Global Payment System The bulk of the work has been geared towards stability and performance of our JRuby stack. Most of our payment plugins are ruby plugins, and it is therefore critical to make sure the system can handle many requests in parallel. Pierre wrote a blog about the performance work which offers more details. In addition to this core platform work, we also developed...
Subscription As A Service Using Kill Bill

Subscription As A Service Using Kill Bill

In the last few months we have been working on extending the Kill Bill multi-tenancy feature. As its core, Kill Bill was designed as a multi-tenant system, where each object (account, invoice, …) pertains to a specific tenant, and where every API in the system carries over the tenancy information. However, to make it fully practical some pieces were missing and have recently been implemented: Ability to upload a per-tenant catalog, Ability to upload per-tenant invoice templates, catalog translations, Ability to upload a per-tenant overdue rules, Ability to upload a per-tenant plugin configurations; for e.g, a given payment plugin can now have separate configurations per tenant allowing to share that plugin across tenants while ensuring that payments get routed to the right place. In the presentation that we made on how we are using the system at Groupon, we highlighted two use cases for Kill Bill. The first use case is what we called Subscription As A Service (or SaaS in that context) and what we want to discuss in that post. It is really about leveraging the multi-tenancy feature so that one deployment can host multiple tenants, each of which corresponding to a specific merchant/product/billing model. But what are the use cases for SaaS exactly? We can think of several use cases: In a large company, where there are many different teams, products, …, we see a lot of opportunities for billing customers using subscriptions and or usage billing model. The traditional approach is to have each team independently solve that problem on its own, ending up with many different solutions, and in many cases ending up with...
Multi-tenancy and Authorization

Multi-tenancy and Authorization

Overview Kill Bill has been designed from the beginning as a multi-tenant system; that is, on one physical Kill Bill deployment, we can have multiple (tenant) instances of Billing/Payment solutions, completely independant with one another. Each of those tenants will have its own catalog and internationalization translations, and will only have access to its own data. In addition to the multi-tenancy, Kill Bill also requires authentication and implements authorization validation on each request. Logically , the multi-tenancy feature and the authentication/authorization are two separate concepts: a given user has access to a (some) specific tenant(s) and that user has some specific set of permissions. The current implementation keeps those two orthogonal, but in the future we may offer the ability to configure the set of permissions associated to a specific user on a per-tenant basis. API Calls When making API calls against Kill Bill, each request needs to pass: The credentials or the sessionId required for the authentication (through HTTP basic authentication), The apiKey (X-Killbill-ApiKey) and apiSecret (X-Killbill-ApiSecret) for the tenant On each request, Kill Bill will validate the credentials are correct (or if there is a sessionId, the validity of that session), The apiKey and apiSecret will be used to retrieve the tenantId and validate the user has access to that tenant. So in the end, only a valid user with the right set of permissions will be able to perform an API call against a tenant she has access to. KAUI Now, let’s look at what happens, when the user is interacting with Kill Bill using KAUI (Kill Bill admin UI): Authentication: User first needs to login,...

Subscriptions: Entitlement, Billing and Dunning

When thinking of subscriptions, the first thing that comes to mind is the idea of receiving a service: You subscribe to your phone company which allows you to make use of your brand new shiny iPhone, or receives your monthly box of organic fair trade certified veggie box,… Now, along with receiving a service, comes the bills! These two sides of the subscription, the entitlement (the service) and the billing (the periodic invoices) are related and yet, they need to have a life of their own to create enough flexibility: For instance, a user may decide to cancel his subscription, and the user (or the company providing the service) may decide that the service should be stopped immediately; the company’s policy may be to avoid any pro-ration credit, requiring the billing to continue until the service period ends, and so entitlement and billing do not stop at the same time. Another example would be to start providing a service in beta mode and only start charging the customer later after enough feedback have been gathered, in which case, entitlement would happen prior billing really starts. Those are two of the use cases to illustrate why entitlement and billing need to be kept separate. Now, there is another set of challenges coming from the recurring payments associated with the invoices: For each invoice (with a balance), there will need to be a payment. The recurring payment could be automatic or the customer could be notified and be responsible to make the payment happen. Some of these payments will fail (CC expired, stolen, insufficient funds,…) and so there is a question...