Kaui Guide

To download a PDF version of this guide, click here.

"Kaui" (KAUI) stands for Kill (Bill) Admin User Interface. This self-contained web application interacts with Kill Bill over HTTPS.

Backoffice staff (for example, Support or Finance) will find Kaui useful to process refunds, credits, chargebacks, and so forth. Kaui also enables the Kill Bill administrator to perform more advanced tasks, such as managing tags, uploading a catalog, and configuring the tenant(s).

Other types of users who might find Kaui useful are developers (for testing), operations, and product managers.

The first half of this guide explains the more basic components:

Advanced and administrative features are covered in the second half of the guide:

The screenshots displayed in this guide may differ from what you see on your Kaui screen. That’s because your user permissions control what features you can access (i.e., what you see on the screen).

If you have any questions about why your Kaui screen doesn’t match what you see in this guide, ask your Kaui administrator.

To log in to Kaui:

To log in to Kaui:

To log out of Kaui, select SIGN OUT in the upper right corner of the Kill Bill homepage:

The homepage is the screen that Kaui displays after you first log in.

Grids (also referred to as tables) appear throughout Kaui to keep lists organized:

For very large grids, use the pagination controls to view different "pages:"

Kaui shows you which column is currently sorted by the purple arrow:

The direction of the arrow (up or down) indicates if the column is sorted in ascending or descending order.

If relevant, you can click a link in the grid to view that item’s detail. For example, on the Invoices grid, click the link to open that specific invoice:

Kaui allows you to edit the columns displayed in a table. To do this, click on the Edit Columns button:

This displays a new menu that lets you select the columns that you would like to view/hide:

You can click on the checkbox next to a column name to show/hide it from the view. For example, in the screenshot below only the Account Id, Name and External Key columns are displayed in the table:

You can also drag and drop a column name to change its position in the table. For example, to display the External Key field as the first column in the table, click the External Key field in the Edit Columns UI, drag it to the top of the list and drop it.

To download the data from a table, click on the Download CSV button:

This displays some additional download customizations:

If you are on the accounts page and would like to download data for all the accounts created in this week, you can select This Week and click the Download button:

On clicking the Download button, a CSV file is generated and downloaded.

By default, only the fields displayed on the screen are included in the CSV. if you would like all the fields to be included, you should click the "All fields" checkbox:

To search for customer accounts, use the basic search. Basic search is available at the top of the screen no matter where you are in Kaui.

Basic search is also available in the center of the homepage:

An advanced search can help you find account information as well as other types of objects in the system:

To perform an advanced search:

You can check the current Kaui version by typing http://<your Kaui URL>/health in the browser. This displays the following:

The Account page has the following sections:

1. Account Sub-Menu

The Account sub-menu organizes and provides access to different areas of the customer’s account:

To see these areas, click the relevant item on the sub-menu. To return to the customer’s Account page, click Account on the sub-menu.

2. Account Information

This section of the screen displays a summary of the customer’s account information, such as their ID, currency, and time zone. To edit this information, click Edit next to Account Information.

Here you can perform the following tasks for the customer account:

3. Personal Information

This section of the screen displays the customer’s personal contact information (read only).

By default, Personal Information details are hidden for GDPR Compliance and customer privacy. To see the information, click Show/Hide Content.

To edit this information, see the Edit an Account section.

4. Billing Info

Here you can perform the following tasks for the customer:

You can also see a summary of billing information:

The Trigger invoice generation feature lets you generate an invoice, either as a test or in a committed state.

5. Payment Methods

This section of the Account page lets you:

For more information on payment methods, see the Payment Methods chapter.

You can make changes to most of the account fields after it has been created.

You can export the data for an account. This creates a text file with the data from all the KB tables for the particular account. Such a text file can then be sent to the KB team for debugging purpose.

If a customer wants to receive email at more than one email address (which is the one defined in the Email field for the account), you can add more email addresses.

To remove additional contact emails:

Use the steps in this section to indicate you will no longer be doing business with a customer. If the customer has unpaid invoices, using the steps below, you can choose to either write off or item-adjust them.

When you link an account to a parent account, the account becomes a child account. Defining a parent-child association between accounts lets you define which entity is responsible for paying the invoice. For more information on this feature, see the Hierarchical Accounts Tutorial.

Issuing a credit in Kaui creates a credit memo. For accounting purposes, the memo is saved with the customer account’s invoices.

Creating a charge in Kaui creates a new invoice. To create a charge:

A customer account can have several payment methods to allow for making payments in different ways, such as credit cards, debit cards, PayPal, and so forth. The payment method includes the details needed for Kill Bill to process a payment against an invoice.

Saving this information in Kaui makes it easier to accept payments from the customer because the customer or service staff don’t need to repeatedly provide their payment method details.

In production systems, payment method information is typically added via gateway-specific data flows. However, developers can use the Payment Method section for testing purposes.

Each payment method is associated with a payment plugin, a type of software that performs the backend processing for that specific payment method. The Plugin name field specifies the name of this payment plugin. (Example: killbill-stripe).

The plugin name is typically mentioned in the plugin’s readme file. For example, in the Stripe plugin readme file, the plugin name is specified in the command line.

To view a payment method after it’s created:

Kill Bill uses the default payment method to automatically pay invoices (whether that invoice is generated by the system or manually by a user).

To set a payment method as the default:

To add a payment method:

This section explains how to apply a transaction to a payment method. These transactions are directly applied on the payment instrument (as opposed to being applied to the unpaid invoice).

Use this functionality only for transactions unrelated to invoices and/or payments.

Example: After paying her final invoice, a customer cancels her subscription and demands a full refund because she is dissatisfied. In this case, you would process this transaction (the refund) against the payment method as explained in this section.

You can perform the following transactions from the Payment Methods section:

To delete a payment method:

This section helps you get familiar with the Subscriptions area of Kill Bill.

For more information on subscriptions, see the Subscription Guide.

To view the subscriptions for an account, open the account and click Subscriptions on the sub-menu. This area of Kaui lists the subscriptions associated with an account.

On the Subscriptions page, you can:

This section explains how to add an add-on product to a customer’s subscription.

Pausing and resuming happens at the subscription bundle level. In other words, pause/resume affects all subscriptions and add-ons in the customer’s account.

You can use the pause/resume feature to:

To pause or resume a subscription bundle, perform the following steps:

In Kaui, you can change a customer’s subscription from one plan to another plan. You can also define a different price than what is set in the catalog and when the change takes effect.

To change an account’s subscription:

To cancel an account’s subscription:

Follow the steps below to update the billing cycle day (BCD) defined for a subscription. These steps assume the subscription is billed on a monthly basis.

If you update the BCD with these steps, the new BCD overrides what is specified in the billing alignment rules in the catalog.

The Invoices page lists the invoices for the currently selected account. To open the Invoices page, open the account and select Invoices on the sub-menu.

Kill Bill generates invoices automatically based on the customer’s subscriptions. However, you can manually create an invoice by creating a charge on the customer’s account.

Click the invoice number to open the Invoice Details page.

The Invoice Details page displays information about the invoice, such as the date it was generated, amount, and so forth.

On the Invoice Details page, you can:

To get to the Invoice Details page:

To make a manual payment against an invoice:

This section explains how to write off an invoice and void an invoice. "Write-off" and "void" have different meanings in Kill Bill:

You can pay all unpaid invoices if a customer account has at least one outstanding invoice. Before you begin, make sure the customer has a valid payment method (see Note).

To pay all invoices:

A dry-run invoice lets you see how a customer’s invoice will look without actually committing it. This feature creates a draft invoice as if it’s being generated on the customer’s bill cycle day. It’s a helpful feature for testing. (You cannot generate a dry-run invoice for an invoice generated from a charge.)

After you generate the invoice, which is in DRAFT mode, you have the choice to commit it. If you do not commit the DRAFT invoice, it remains in the system as a draft.

In order to generate a dry-run invoice, the customer account must be associated with a subscription that has a billing date in the future.

The Payments page lists any payments applied to invoices for the customer account. This page also lists information about scheduled payment retries for failed payments.

To open the Payments page, open the account and select Payments on the sub-menu.

Kill Bill automatically generates a payment for an invoice if an account:

Kill Bill does not automatically generate an invoice payment if:

The Payment Details page displays information about a specific payment, such as the date it was generated, amount, and so forth. Below the payment information is information about the payment method used.

On the Payment Details page, you can: refund a payment or perform a chargeback.

To get to the Payment Details page:

When you refund a payment from the Payment Details page, it brings the invoice amount to zero (i.e., the invoice will have no balance). You can also perform a partial refund in which the partial refund amount is added as an invoice line item.

The refund is applied to the same payment method used in the original payment.

To refund a payment:

If your business receives a chargeback notice for a payment, you can record that chargeback in Kill Bill.

The Timeline displays a chronological list of events (that is, an audit log) that occurred for a specific customer account. You cannot make changes to the timeline.

To see the Timeline, open an account and click Timeline on the sub-menu:

On the Timeline page, you can:

For each Kill Bill deployment, you can run multiple tenants. A few examples of running different tenants for your organization incude:

To create additional tenants, follow the steps below.

This section explains the main areas of the Tenant Configuration page.

1 Tenant Details

This read-only area displays basic information about the tenant.

2 Useful Links

Click on a link to go to the associated list.

3 Allowed Users

This section displays the users who have permission to log on to this tenant. You can click on the user name to view that users’s details or click on the plus sign to add a new user for the current tenant.

By default, the admin user has access to the tenant.

To add a user from this screen, see Add an Allowed User to the Tenant. For more information, see the Users, Roles, and Permissions chapter.

4 Tenant Configuration Tabs

The tabs at the bottom of the Tenant Configuration page allow you upload various files that are specific to the current tenant:

The steps below explain how to add an existing user to the current tenant. Before you begin, you should have created the user in the Kill Bill system by following the steps in the Add a User section.

Perform the steps below to remove a user from the current tenant. Note that this does not delete the user from the Kill Bill system.

In this guide, "users" refers to those who log in to Kaui to perform actions (add a charge, generate a dry-run invoice, etc.). However, other parts of the documentation also use the term "user" when referring to users of the API.

In order for Kaui users to be able to log in and perform tasks, you need to create a user profile for each one. A user profile stores the username and password as well as the following:

In this section, you’ll learn how to manage users in Kaui, which includes:

Before you begin working with users, make sure that:

In addition, you should already have at least one tenant set up in Kaui.

For additional information on managing users, roles, and permissions in Kill Bill, see the following:

The role (or roles) assigned to a user defines which tasks the user can perform in the system (for example, perform a chargeback or add a custom field).

To create a user role:

To open a list of Kaui users:

At the top of the screen, click the gears icon and select Users.

Kaui displays the Users screen:

On this screen, you can add a user by clicking the plus icon. To open a user’s details to edit or delete, click the username.

Use the steps in this section to change the user’s name, password, or role.

The following steps explain how to delete a user from the system (i.e., for both Kaui and Kill Bill). Deleting a user also removes the user’s access to any assigned tenants.

This chapter explains how to use the Catalog Show tab to create and manage catalogs:

On this tab, you can also add a currency to a plan.

You can view the current catalog’s products and plans on the Catalog Show tab located at the bottom of the Tenant Configuration page.

To get there:

For additional field information, see the Catalog API.

The Kill Bill catalog is stored in XML format. This section explains how to upload an XML file that contains the product catalog information.

If you are replacing a catalog with a newer version, ensure that <catalogName> in the XML file is the same as the existing catalog. The catalog filename does not need to be the same.

To upload an XML catalog in Kaui:

The steps below explain how to download the current Kill Bill catalog in XML format.

Kaui lets you configure basic settings for how the system behaves when an account is overdue. For overdue configuration, you define:

These three pieces of information make up the overdue flow.

Overdue configuration applies at the tenant level. However, you can also configure overdue flows for the global Kill Bill system.

In Kaui, overdue configuration is a subset of the full overdue configuration settings. For more information on the full configuration settings and global settings, see the Overdue System Guide.

See the following sections to create overdue (dunning) flows for a tenant:

If any overdue (dunning) flows are configured, you can see them on the Overdue Show tab at the bottom of the Tenant Configuration page. To get there:

The following steps explain how to set up overdue flows (i.e., actions) for the tenant.

Kill Bill overdue configuration is stored in XML format. This section explains how to upload an XML file that contains the overdue configuration.

Kill Bill supports the ability to generate emails and invoices in various languages as long as the required translation files are present in the system. Three tabs on the Tenant Configuration page enable you to upload these files:

The functionality of these tabs is very similar. To avoid repetition, we’ve included instructions for just one tab, with any differences noted.

To get there:

In Kaui, you can apply one or more tags to accounts and invoices, a tag being a single value. Tags in Kill Bill can be used to convey information about an object type. A tag can just provide information about an object (user tag) or it can actually affect how the object is handled in Kill Bill (control tag).

This section explains how to attach tags to accounts and invoices. It also describes the steps for creating the tag definitions on which a user tag is based.

API Reference:

To see a list of all available tags in the current tenant, select the tag icon at the top of the screen, then select Tag Definitions:

Kaui displays the Tag Definitions page.

This section explains how to view objects that have attached tags. You can view all the objects with tags for the current tenant; you can also view the tags for a specific account (or invoice).

To see a list of all the objects in the tenant with an attached tag, select the tag icon at the top of the screen, then select Tags:

Kaui displays the Tags page.

To see any tags assigned to a specific account (or invoice):

Kaui opens the Tags page and displays only the tags assigned to that account (or its related invoices and subscriptions).

To create a new tag definition:

In Kaui, you can delete a tag definition from the current tenant only if the related tag hasn’t been attached to an object. If you try to delete such a tag definition, Kaui will prevent you.

To delete a tag definition:

In Kaui, you can attach tags to accounts, invoices, and subscriptions. Attaching or removing a tag is basically the same whether it’s an account, invoice, and subscription. The steps below explain how to attach and remove a tag to an account.

Kill Bill enables you to create custom fields (key/value pairs) and attach them to objects like accounts, payments, and so forth. When used with custom plugins or third-party applications, custom fields can extend Kill Bill’s functionality .

This section explains how to create custom fields and attach them to objects.

This section explains how to view all of the custom fields defined for the tenant as well as the associated objects.

At the top of the screen, click the tag icon and select Custom Fields.

Kaui displays the Custom Fields page:

This section explains how to view any custom fields for a specific account or other objects associated with that account (e.g., invoices, payments, subscriptions).

Kaui opens the Custom Fields page and displays only the custom fields assigned to that account or its related objects:

To create a custom field and attach it to an object:

The KPM page is only available when the KPM plugin has been deployed.

It lets you install and uninstall plugins, as well as start, stop, and restart them at runtime:

In order to deploy a plugin via Kaui, you need to do the following:

Once the plugin download is complete, it will appear in Stopped status. To start the plugin, click on the Start button.

The Analytics page is only available when the analytics plugin has been deployed.

It lets you display custom metrics with filtering capabilities. We provide a few by default, but the analytics framework lets you add any desired metric.

Here we show the MRR by plan over time:

For more information, see the Analytics Guide.