When Stéphane and Pierre began developing Kill Bill in 2010, the open-source software they created was a direct result of their experiences in working with the billing and payments startup and enterprise organizations. From the very beginning of this project, they considered the subscription billing APIs one of the most important aspects of Kill Bill – if not the most important.
Nowadays, API design-first is common, but we still think it’s important to stress the fact that the Kill Bill co-founders designed it to be software for building your own billing and payments platform. The APIs are the heavyweight lifters that are going to get you there.
For that reason, they’re the topic of this month’s blog post. We can’t cover all of the API functionality in one blog post, but we will hit the high points.
Three Types of Subscription Billing APIs
The first type is the REST API, which communicates with the core system. Using 250+ endpoints, you can manage all of Kill Bill’s resources, such as accounts, subscriptions, and so forth.
The API uses POST, GET, PUT, and DELETE to invoke CRUD operations (Create, Read, Update and Delete). It uses HTTP response codes to indicate errors. All of this is done using JSON input and output.
The second type is the Java API, which the Kill Bill plugins can use to make requests. And the core system interacts with these plugins via the third type, the Java plugin API.
Any developer familiar with Java, PHP, Python, Ruby, Node, or Go can implement Kill Bill using its APIs. Community-supported libraries are also available. Our API reference includes samples in cURL, Java, Ruby, and Python.
For this blog post, we’ll focus on the REST APIs because they cover Kill Bill’s out-of-the-box functionality. (If you’re interested, last month we mentioned the Java API in a blog post on plugins. You can also learn more about the other two APIs in the Plugin Introduction.)
REST APIs
Whether your intention is to create a customer interface via the browser, an internal interface for your back-office staff (though Kaui already handles a wide variety of these tasks), or a reporting module for your executives, the Kill Bill subscription billing APIs can handle it all. Let’s look at the most significant components:
- Account
- Catalog
- Subscription
- Invoice
- Payment
Account
The Account resource stores the customer-related information. Per-account information, like subscriptions, invoices, and payments, are linked to the customer account.
You can use the Account component of the API to enable customers to set up their own account, view invoices, update billing information, and even change or cancel their subscriptions.
Catalog
The XML-formatted catalog stores all the information about what your organization sells and how to sell it (products, plans, pricing, rules, etc.). Obviously, you want access to that!
The Catalog API lets you upload and retrieve the catalog and includes endpoints for getting subscription information (those plans, phases, prices, products, and so forth). This API also includes a nifty little Simple Plan endpoint to get you started quickly with a simplified Kill Bill catalog – check it out!
Subscription
In Kill Bill, a subscription is a “contract” between the customer (account) and your organization to purchase a certain product/service with particular terms. The Subscription API enables you to create, change, and cancel subscriptions by getting the particulars of a subscribed plan from the Kill Bill catalog.
Besides the plan, an account, and a start date, the subscription resource includes attributes that provide two parallel views of the subscription – the entitlement portion and the billing portion. The design provides a loose coupling between billing (when to invoice) and entitlement (when to allow access to the system) to accommodate so many different use cases.
Invoice
In a plain-vanilla world, you have a customer with an account that has a subscription, and you bill for that subscription on an invoice. Pretty simple.
Yet in the billing world, you need to be ready to bill for anything and everything: outstanding charges, fixed price, recurring charges, usage charges, adjustments, and (sadly) taxes. Kill Bill is, of course, designed to handle these scenarios, though taxes are calculated outside of Kill Bill and added to the invoice via a tax plugin (which is a specialized type of invoice plugin).
The Invoice component of the API includes separate resources for the invoice and invoice items, and it also supports the parent-child hierarchical model for invoicing of the parent or children accounts. To reflect your organization’s brand and/or international presence, the Invoice component can fetch the appropriate templates for formatting and translation files for, well, translating.
Last but not least is the Dry-Run Invoice, which lets you preview the generated invoice with no effect on the actual system. This allows you to test how the invoice would look on a certain date or you make certain changes.
Payment
The payment world has made gigantic leaps and bounds since the days when credit cards were the sole means of non-cash payment. When you think of all the payment methods that are now available to consumers, it’s not just amazing, it’s also a reminder to keep your payment methodology flexible. You just don’t know what new payment player will make a big splash next in the industry.
A payment gateway plugin (one of those Java APIs we mentioned earlier) handles the communication with your organization’s chosen payment gateway. Kill Bill does not store any payment method details, as that is typically handled by the gateway.
The Payment component is supported by the Payment Method, Payment Transaction, Invoice Payment, and Credit components. A sampling of the feats you can accomplish with the Payment APIs includes:
- Managing payment methods
- Authorizations
- Chargeback reversals
- Chargebacks
- Voids
- Refunds
- Routing*
* Kill Bill supports payment routing, where the choice of the payment gateway is decided at run time based on custom business rules. Its use requires a payment control plugin.
Is That It?
Nope! What we discussed above are the stars of the Kill Bill REST API, but we’re going to summarize the other components to help you put it all in context:
- Admin—A handful of administrative and operational endpoints, plus a low-level view endpoint thrown in for good measure.
- Bundle—In actuality, subscriptions are organized into a higher-level bundle (even if that bundle contains only one subscription). Grouping related subscriptions into a bundle ensures that certain operations propagate to the group. For example, if you cancel the base subscription, its add-ons are also automatically canceled.
- Custom Field—A custom field is a key-value pair, and in Kill Bill, you can attach it to nearly any resource. These endpoints let you search for and list any custom fields along with the resources they are assigned to.
- Tag—Tags are similar to custom fields (above), but instead of being a key-value pair, it’s a single value (Example: VIP). The Tag endpoints let you search for and list any tags along with the resources they’re associated with.
- Tenant—Kill Bill is a multi-tenant system (a tenant is a single Kill Bill deployment), and these endpoints enable you to create tenants and set system configurations at the tenant level to override the system-level ones (this also applies to plugin configuration settings). You can also set the tenant to receive push notifications about events from the system.
- Usage—To invoice usage-based subscriptions, these endpoints provide a way to record and retrieve usage data in Kill Bill.
We’ve summarized quite a bit here, so we recommend that your next step in learning about the Kill Bill subscription billing API is to read Using Kill Bill APIs.
