Introduction

PDF Version of Kaui Guide

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

What Is Kaui?

"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.

Note: For Developers: Kaui functionality is provided via a series of Ruby on Rails mountable engines. You can extend its functionality (for example, to provide a custom UI for your plugins) by mounting your own engine(s).

How to Use This Guide

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

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

Note: The Plugin Manager and Analytics functionality is currently undocumented.

About Screenshots

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.

Other Learning Resources

Videos

We regularly add new overviews and tutorials to our YouTube videos, so check in from time to time.

Glossary

The terms listed below are used frequently in this guide. We’ve provided an abbreviated description below. For a full description, see the Kill Bill Glossary.

Account (a.k.a. customer account)

A record that contains details about the customer (name, address, etc.).

Child

An account that is associated with a parent account.

External Key

An alternative unique ID for an object.

Parent

An account that contains one or more child accounts.

Payment Method

A record of the details required for Kill Bill to trigger a payment.

Permissions

In Kill Bill, a defined action that can be performed in a system (for example, TAG_CAN_ADD OR ACCOUNT_CAN_CREATE). You can assign one or more permissions to a role, which can then be associated with a user. The user can only perform the permissions associated with that role.

Plan

Define how much a customer pays for a product and the frequency of the payment.

Plugin

Software that runs alongside Kill Bill in order to provide additional functionality.

Phase (a.k.a plan phase)

Time periods within a subscription during which certain rules apply.

Subscription

A contract between you (the business) and a customer that associates an account with a plan and a specific start date.

Tag

A property that can be added to an object (for example, an account or a subscription) for information purposes or to affect the behavior of the system.

Tenant

The division or organization that is using Kill Bill as a group of users. Note that an organization can have more than one tenant, as Kill Bill supports multi-tenancy.

User

A person who logs on to use Kaui.

User Role

A group of permissions that specify which actions the user is allowed to perform in Kaui. A user can have multiple roles. A role can have multiple permissions.

Getting Started

First-Time Login

Note: Kill Bill handles authentication. The method your organization uses to manage users is highly configurable. For information on managing users and permissions, see the Users chapter.

To log in to Kaui:

  1. Type in your username and password, then select the Sign In button.

    LoginScreen

    Kaui displays the Add New Tenant screen:

    AddNewTenant

  2. Enter the tenant Name, API Key, and API Secret.

    Note: The API key and API secret pair are used in all HTTP requests to ensure that the user issuing the request has the correct permissions to access the tenant.

  3. Click the Save button.

Log In to Kaui

To log in to Kaui:

  1. Type in your username and password, then select the Sign In button.

    LoginScreen

  2. If your organization uses more than one Kill Bill tenant, select the tenant from the dropdown.

  3. Click the Save button:

    ChooseTenant

Log Out of Kaui

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

SignOut Labeled

Homepage Layout

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

Homepage Labeled

  1. Basic Search

  2. Advanced Search

  3. Plugin Manager and Analytics

  4. Tags and Custom Fields

  5. Users, Tenants, and Admin

  6. Username / Tenant name and logout

  7. Latest invoices, accounts, and payments (latest records created for this tenant)

  8. This is Killian, the Kill Bill mascot!

Return to Homepage

From any screen in Kill Bill, you can return to the homepage by clicking the logo in the upper left corner:

killbill logo LARGER

Icons

Icon Description

i PlusGreen

Add—Indicates you can add an item, such as a payment method, credit, charge, etc.

i InvoiceGen

Dry-run invoice—Appears on the Account page. Clicking it manually triggers a committed or dry-run invoice.

i DownArrow

Expand—Expand a section or dropdown menu.

i UpArrow

Collapse—Collapse a section.

i Tag

Tags—_Admin-level feature:_ On the home page, click to access Tags, Tag Definitions, and Custom Fields.

All users: In other locations in Kaui, click to select a tag to apply to the current object (for example, an account).

i Plug

Kaui Package Manager—Appears at the top of the screen and gives you access to plugin specific screens. (Also known as Kill Bill Plugin Manager.)

i Addon

Add-on—Appears on the Subscription screen and lets you add an add-on to the account’s subscription.

i CreditCard

Make a payment—Appears on the Invoice screen and lets you make a payment against the invoice.

i Gears

Users, Tenants, & Admin—_Admin level feature:_ Appears at the top of the screen and gives you access to Users, Tenants, and Admin.

i Refresh

Appears in the Payment Methods section of the Account page, clicking the Refresh icon triggers a refresh for each payment plugin installed in Kill Bill, for that account. When you refresh a payment method, Kill Bill retrieves the latest payment information from where it’s stored (for example, from Stripe or another payment gateway).

Note: This icon does not display if the only payment method listed is EXTERNAL_PAYMENT.

Grids/Tables

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

GridSample

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

80

To sort columns on a grid, click the up/down arrow in that column’s header:

ShowSortArrowsOnColumn

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

ShowSortByColumn

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:

ClickToViewDetail
Tip: To view all accounts, place your cursor in the search field and press the Enter key.

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.

ShowTopSearch

You can search for an account using the following criteria:

  • Account ID

  • External key

  • Name

  • Email address

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

ShowSearchHomepage

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

  • Bundle

  • Credit

  • Custom field

  • Invoice

  • Invoice payment

  • Payment

  • Subscription

  • Tag

  • Tag definition

  • Transaction

To perform an advanced search:

  1. On the homepage, click Advanced search:

    ShowAdvancedSearch

    Kaui displays the Advanced Search pop-up:

    AdvancedSearchPopup

  2. In the Object type field, select the object type you want to search for:

    AdvSearch ObjectTypeDropdown
    Note: For information on which fields are searched for each object type, see the table in the next section.

  3. In the Search for field, enter the identifier (ID) of the object you’re searching for. (Example: If you’re searching for a specific invoice, type in the invoice number.)

  4. If you want Kaui to search and display the first record in the search results, click the Fast search checkbox.

  5. Click the Search button. Kaui displays the search results.

Tip: At the bottom of the Advanced Search pop-up, Kaui displays the search syntax. You can copy and paste this advanced search syntax into a basic search field. This is helpful if you frequently perform the same kinds of advanced searches. For example:
AdvancedSearchSyntax Labeled

Searchable Fields by Object Type

Object Type Searchable Fields

Account

account ID, name, email, company name, external key

Bundle

account ID, bundle ID, external key

Credit

invoice item ID

Custom field

custom field ID, field name, field value, object type

Invoice

invoice number, invoice ID, account ID, currency

Invoice payment

payment ID

Payment

payment ID, external key

Payment method

payment method ID, external key

Subscription

subscription ID, external key

Tag

tag ID

Tag definition

tag definition ID

Transaction

transaction ID, external key

Accounts

This section helps you become familiar with customer accounts and the layout of the Account page.

The Account page provides information about a specific customer, such as email address, physical address, and so forth. It is also the central location for the customer’s billing information, subscriptions, invoices, and payment methods.

The next section explains how the Account page is laid out. To skip this and see the task-based steps, see Create an Account.

Account Page Layout

The Account page has the following sections:

  1. Sub-menu

  2. Account information

  3. Billing info

  4. Personal info

  5. Payment methods

AccountPage Labeled

1. Account Sub-Menu

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

Account Submenu

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:

Field Description

Account balance

Amount of money due on the account, including any account credits.

Account credit

Amount of any money owed to the customer.

Overdue status

The status of the customer’s account that indicates if they are overdue or up-to-date on their invoice payments.

Note: The account can have a negative account balance, but not be overdue. That’s because overdue status depends on invoice due dates and how late payments are defined based on a company’s business policy. For example, an invoice may not be overdue if a company allows a 15-day grace period (a.k.a. NET terms) to make a payment.

Bill cycle day (BCD)

The day of the month on which the system generates an invoice for this account. This field applies to accounts that are subscribed to monthly subscriptions (or a multiple of monthly, such as quarterly, annually, etc.). For more information, see the Account Field Descriptions table.

Next invoice date

The date on which the system generates the customer’s next invoice.

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.

Create an Account

  1. At the top right of the screen, click Create New Account:

    CreateNewAccount Labeled

  2. Kaui opens the Add New Account screen:

    AddNewAccount

  3. Fill in the fields. For field descriptions, see Account Field Descriptions.

  4. Click the Save button.

Account Field Descriptions

Field Description

Name

The customer’s first and last name.

First name length

This field sets the length of the customer’s first name. Kill Bill automatically calculates this number based on the location of the space between the first and last name. You can overwrite it with a different number, if necessary.

Note: This field is used if your organization needs to extract customers' first or last names for communication (invoices, emails, etc.). The field lets an organization accommodate variations of names used across the globe.

External key

An optional alternate ID for the account. Once this is saved for the customer, you cannot change it.

Tip: The external key feature is helpful if you integrate Kill Bill with another system, such as a CRM, and want to use that system’s ID in Kill Bill (for identification, searching, and so forth). Once this is set and saved for the customer, you cannot change it.

Email

The main email address to use for communicating with the customer.

Bill cycle day (BCD)

For monthly or quarterly subscriptions, what day of the month the invoice is created. Once this is saved for the customer, you cannot change it.

Note: The system has three types of billing (date) alignment that affect the BCD: ACCOUNT, SUBSCRIPTION, and BUNDLE. For more information about the three billing alignment types, see Catalog Examples and "Billing Alignment Rules" in the Subscription Guide.

Currency

The currency that the customer uses to make purchases. Once this is saved for the customer, you cannot change it.

Timezone

The time zone in which the customer resides. Once this is saved for the customer, you cannot change it.

Locale

Indicates the language that Kaui uses to send communication to the customer (invoices, emails, etc.) If your organization communicates with customers in a language that’s different than the system’s default language, it’s important to select the appropriate locale for the customer. For more information, see the internationalization overview document.

Address line 1 and Address line 2

The street address where the customer resides.

Zip code

The zip code for the area in which the customer resides.

Company

If relevant, the company/organization the customer works for.

City

The city in which the customer resides.

State

The state in which the customer resides.

Country

The country in which the customer resides.

Phone

The customer’s phone number.

Notes

Additional information about the account. These notes are not viewable by the customer.

Migrated?

This field is for informational purposes only. You can check this box if you have migrated this customer account into Kill Bill.

Contact email addresses

Additional addresses to which account-related emails will be sent. The email addresses listed here will receive the same emails as the main Email address. For more information, see Add Additional Contact Emails.

Edit an Account

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

Note: You cannot change the following fields: Bill Cycle Day, Currency, External Key, and Time Zone.

  1. Open the account on the Account page.

  2. Next to Account Information, click Edit.

    Kaui opens the Update Account screen:

    Account UpdateScreen

  3. Make changes to the fields. For field descriptions, see Account Field Descriptions.

  4. Click the Save button.

Export Account Data

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.

  1. Open the account on the Account page.

  2. Next to Account Information, click Export.:

    Account Export Label

  3. Kaui creates a text file with the account data.

Add Additional Contact Emails

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.

  1. Open the account on the Account page.

  2. In the Personal Information section, click the gray down arrow i GrayDownArrow to expand the section.

    PersonalInformation

  3. Click the plus sign i PlusGreen next to Contact emails.

    Kaui opens the Add New Email screen:

    AddNewEmail

  4. Type in a single email address.

  5. Select the Save button. Kaui returns to the Account page.

  6. To see the email address you added, expand the Personal Information section:

    NewContactEmail

  7. To add another email address, repeat steps 2 - 5.

Delete Additional Contact Emails

Warning: Kaui does not ask you to confirm your deletion; use this feature with caution.

To remove additional contact emails:

  1. Open the account on the Account page.

  2. In the Personal Information section, click the gray down arrow i GrayDownArrow to expand the section.

  3. Next to the email you want to delete, click the red X. Kaui immediately deletes the email address.

Close an Account

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.

Note: Closing an account does not delete it. It only indicates the account is no longer a customer of yours. Once you close the account, its data becomes read-only, and you cannot make changes to it.

  1. Open the account on the Account page.

  2. Next to Account Information, click Close.

    Kaui displays the Close Account pop-up:

    CloseAccountPopup

  3. Check the Name and Account ID fields to ensure you are closing the correct account.

  4. Toggle any of the following options:

    • Cancel All Subscriptions—Stops any subscriptions that are current for this account.

    • Write Off Unpaid Invoices—Brings the balance for all unpaid invoices to zero. When you choose to write off the invoice, it is removed from Account Receivables.

    • Item Adjust Unpaid Invoices—Adds an invoice line item with a negative amount to bring each unpaid invoice’s balance to zero.

      Note: The last two options are mutually exclusive (i.e., you can only select one of them).

  5. Click the Close button.

    Kaui displays a message that lets you know the account was closed. In addition, the Account sub-menu displays "Closed:"

    AccountSubmenu Closed

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.

  1. As a preparation step, open the parent account and copy the account ID in the Account Information section.

  2. Open the account that will become the child account.

  3. In the Account Information section of the child account, click the plus sign icon i PlusGreen next to the Parent field:

    Account ParentField Labeled

    Kaui opens a pop-up:

    LinkToParentPopup

  4. Click in the Parent account id field and paste in the account ID that you copied in step 1.

  5. To set the parent as responsible for all payments associated with this account, check the Is payment delegated to a parent? box. If you do not check this box, the child account is responsible for its own payments.

  6. Click the Save button. Kaui displays the parent account ID as a link in the Account Information section.

    Account ParentID Labeled

    You can open the parent account by clicking the account ID link.

Add Credit to an Account

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

  1. On the Account page, click Add Credit at the top of the Billing Info section.

    AddCredit Labeled

    Kaui opens the Add New Credit screen:

    AddCreditPopup

  2. Fill in the fields:

    • Amount—The amount of the credit.

    • Currency—The currency defaults from the customer account and should not need to be changed.

    • Reason—The reason is automatically selected based on Kaui configuration settings. However, you can make a different selection.

    • Comment—The text you enter here displays on the Timeline page after saving the credit. Adding comments is optional.

  3. Click the Save button. To view the credit, select Invoices on the sub-menu.

    On the Account page (in the Billing Info section), Kaui adjusts the account balance and account credit accordingly.

Create a Charge on an Account

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

  1. On the Account page, click Create Charge at the top of the Billing Info section.

    CreateCharge Labeled

    Kaui opens the Add New Charge screen:

    AddNewChargePopup

  2. To set the invoice as a draft instead of immediately committing it, uncheck the Auto-commit box.

  3. Fill in the fields:

    • Amount—The amount of the charge.

    • Currency—The currency defaults from the customer account and should not need to be changed.

    • Description and Comment—What you type here displays on the customer’s invoice. Both fields are optional.

  4. Click Save and Kaui generates an invoice.

  5. If you unchecked the Auto-commit box and have changed your mind, you can click the text Commit at the top of the page.

    If you do not commit the invoice, it will stay in Draft mode. You can commit it by opening it from the Invoices page and clicking Commit.

    On the Account page (in the Billing Info section), Kaui adjusts the account balance to reflect the amount of the charge.

Payment Methods

Overview

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.

Note: Although you can’t edit a payment method, you can delete it.
Warning! For PCI compliance, do not enter any genuine payment information in these fields.

About Payment Plugin Names

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.

View Payment Method Details

To view a payment method after it’s created:

  1. Open the account on the Account page.

  2. In the Payment Methods area, click the gray down arrow i GrayDownArrow next to the payment method.

    Kaui expands the details for the payment method:

    PaymentMethod Expanded

Set a Payment Method as the Default

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:

  1. Open the account on the Account page. In the Payment Methods section, click the star icon i StarClear next to the relevant payment method:

    PaymentMethodStar Labeled

    The filled star i StarFilled indicates it’s now the default payment method.

Add Payment Method

To add a payment method:

  1. Open the account on the Account page.

  2. Next to Payment Methods, click the plus sign:

    PaymentMethods PlusSign Labeled

    Kaui displays the Add New Payment Method screen:

    AddPaymentMethodScreen

  3. Fill in the fields. For field descriptions, see Payment Method Field Descriptions.

  4. Click the Save button.

Payment Method Field Descriptions

Field Description

External key

An optional alternate ID for the payment method. Once this is saved for the customer, you cannot change it.

Plugin name

Type in the name of the plugin that is associated with this type of payment method.

Each payment method is associated with a payment plugin that does the backend processing related to the payment method. The Plugin name field specifies the name of the payment plugin associated with the payment method (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.

Card type

The name of the credit or debit card.

Card holder name

The name that appears on the card.

Expiration month Expiration year

The month and year the card expires. Enter month as mm and year as yy. (Examples: 07 for the month of July and 23 for the year 2023.)

Credit card number

The credit card number, typed without dashes.

Address 1, Address 2, City, ZIP code, State, Country

The billing address associated with this card.

Add property (Name/Value)

Use the Name/Value fields to assign custom fields and values to the payment method.

Note: Custom fields are an advanced feature. For more information, see Custom Fields.

Default payment method?

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

Note: If you forget to select this box, you can set the payment method as the default by clicking the star icon next to the payment method on the Account page:

PaymentMethodStar Labeled

Apply a Transaction to 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:

  • Authorize

  • Capture

  • Credit (see note)

  • Purchase (i.e., charge)

  • Refund

  • Void
Note: "Credit" here refers to depositing funds directly to the customer card and is unrelated to account credits.

  1. Open the account on the Account page.

  2. In the Payment Methods area, click the gray down arrow i GrayDownArrow next to the payment method.

  3. Select the type of transaction you want to perform:

    Payment Method Transactions
    Note: This area lists Authorize, Purchase, and Credit. For other transaction types, click any of these options. You will be able to change the transaction type on the next screen.

    Kaui displays the Process Transaction screen:

    ProcessTransaction

  4. Fill in the fields. For field descriptions, see Process Transaction Field Descriptions.

  5. Click the Save button. Kaui saves the transaction and displays it on the Payments page.

Process Transaction Field Descriptions

Field Description

Transaction type

From the dropdown list, select the type of transaction you want to perform.

Amount

The amount of the transaction.

Currency

The currency to use for the transaction. This field defaults from the customer account.

Payment key

The unique payment key (ID) to which you want to apply the transaction. This field is required for transaction types that are applied to a specific payment (Capture, Chargeback, Refund, Void).

Note: You can copy the payment key for a specific transaction from the External Key column of the Payments page. Or you can copy it from the URL displayed on your browser’s address line:

Example:

URL: https://demo.killbill.io/accounts/cb736a4f-9b56-4074-ae07-1d37b37cb69f/payments/0d1e11e5-2df6-4b6b-992f-e9ff2de38cef

Payment key: 0d1e11e5-2df6-4b6b-992f-e9ff2de38cef

Transaction key

Kill Bill automatically generates an external transaction key for Authorize, Purchase, and Credit transactions. To process a transaction that requires the transaction key, open the payment detail from the Payments screen and copy the key from the Transaction External Key column.

image::../assets/img/kaui/TransactionKey-Labeled.png[width=350,align="center"]

Reason

The reason is automatically selected based on Kaui configuration settings. However, you can make a different selection.

Comment

The text you enter here displays on the Timeline page after the transaction is complete. Adding comments is optional.

Add control plugin

For information on control plugins, see Plugin Manager.

Add property (Name/Value)

Use this area to assign custom fields and values to the transaction. For information on custom fields, see Custom Fields.

Delete Payment Method

Warning: Kaui does not ask you to confirm your deletion; use this feature with caution.

To delete a payment method:

  1. Open the account on the Account page.

  2. In the Payment Methods area, click the red X next to the payment method. Kaui immediately removes the payment method.

Subscriptions

Overview

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

For more information on subscriptions, see the Subscription Guide.

Open Subscriptions Page

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.

Subscriptions

On the Subscriptions page, you can:

Add a Subscription

Note: To create a subscription, you must have at least one product and one plan defined in the catalog.

  1. On the Subscriptions page, click the plus sign to the right of Subscription Bundles:

    SelectAddSubscription

    Kaui displays the Add New Subscription screen:

    AddNewSubscription

  2. Fill in the fields. For field information, see Add Subscription Field Descriptions.

  3. Click the Save button.

Add Subscription Field Descriptions

Field Description

Bundle Key

If you leave this field blank, Kill Bill generates a unique bundle key. If necessary, you can enter a different bundle key.

Subscription Key

If you leave this field blank, Kill Bill generates a unique subscription key. If necessary, you can enter a different subscription key.

Plan

Select the plan from the dropdown list. These options come from the plans defined in the catalog.

Price Override

If you need to override the price for the plan you’ve selected, enter an amount in this field.

Immediate Creation

Select this option to start the subscription immediately.

Specify a date

To define a specific date on which the subscription begins, select this option, and choose a date from the Date field that appears.

Add an Add-On Product to a Subscription

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

Note: To add an add-on to a subscription, the add-on must exist in the catalog and be available in the base plan.

  1. Open the account and click Subscriptions on the sub-menu.

  2. Hover over the gift icon and click Add add-on:

    Subscriptions SelectAddOnIcon

    Kaui opens the Add New Add-On screen:

    AddNewAddOn

  3. Fill in the fields. For field information, see Add New Add-On Field Descriptions.

Add New Add-On Field Descriptions

Field Description

Subscription Key

Note that this subscription key applies to the add-on, not the original subscription. If you leave this field blank, Kill Bill generates a unique subscription key. If necessary, you can enter a different subscription key.

Plan

Select the add-on to add to the subscription.

Price Override

If you need to override the price for the add-on you’ve selected, enter an amount in this field.

Immediate Creation

Select this option to start the subscription immediately.

Specify a date

To define a specific date on which the subscription begins, select this option, and choose a date from the Date field that appears.

Pause/Resume Subscriptions

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.

Note: While a customer’s subscription bundle is paused, you cannot add any new subscriptions or add-ons to the account.

You can use the pause/resume feature to:

  • Stop a subscription bundle indefinitely

  • Reactivate a paused subscription bundle

  • Set a specific time period during which the bundle is paused and then automatically resumed

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

  1. Open the account and click Subscriptions on the sub-menu.

  2. Hover over the gift icon and click Pause / Resume:

    Subscriptions SelectPauseResume

    Kaui opens the Pause/Resume screen:

    Subscriptions PauseResume

  3. Fill in the following fields:

    • Pause date—The calendar date on which to temporarily stop the subscription bundle. To resume a paused subscription, leave this field blank.

    • Resume date—The calendar date on which to remove the pause from the subscription(s). To set a pause to continue indefinitely, leave this field blank.

    • Comment—The text you enter here displays on the Timeline page after saving the pause/resume. Adding comments is optional.

  4. Click the Pause / Resume button. Kaui displays a success message at the top of the screen.

Change a Subscription

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:

  1. Open the account and click Subscriptions on the sub-menu.

  2. In the Actions column (far right), click Change.

    SelectChangeSubscription

    Kaui opens the Change Subscription screen:

    ChangeSubscription

  3. In the New plan field, select a different plan.

  4. If you need to override the price for the plan you’ve selected, enter the amount in the Price Override field.

  5. To accept the system’s default policy for changing subscriptions (END_OF_TERM), leave Default policy selected and click Save.

    OR

    You can select one of two other options: Specify Policy or Specify a date. This will override the policy defined in the catalog for the plan. For information on this topic, see "Plan Change Timing" in the Subscription Guide.

    • Specify Policy: You can select either IMMEDIATE or END_OF_TERM. For information on these two policies, see "Subscription Alignment Rules" in the Subscription Guide.

      ChangePlan SpecifyPolicy

    • Specify a date: Click on this and choose a date from the Change Date calendar that appears. Make sure to choose an effective date that is in the future.

      ChangePlan SpecifyDate

Cancel a Subscription

To cancel an account’s subscription:

  1. Open the account and click Subscriptions on the sub-menu.

  2. In the Actions column (far right), click Cancel.

    SelectCancelSubscription

    Kaui displays several options. The option you select defines how Kill Bill handles billing for the canceled subscription:

    Subscriptions CancelOptions

Cancellation Options

Option Description

Cancel (default policy)

Uses the default policy specified for the plan in the catalog.

Cancel start of term (full credit)

Cancels the subscription immediately and refunds whatever amounts have been paid toward the subscription.

Cancel immediately (partial credit)

Cancels the subscription immediately and applies a partial credit to the account based on how much of the service has been consumed.

Cancel end of term (no credit)

Cancels the subscription at the end of the billing period with no refund to the customer. Note that after using this option to cancel, you can still reinstate the customer (i.e., reverse the cancellation).

Cancel a subscription given a date

If you select this option, Kaui displays a pop-up from which to choose a date:

CancelSubGivenDate

Use requested date for billing: To set the entitlement date and billing date the same as the date you just selected, check this box.

Otherwise, if you leave the checkbox empty, the entitlement date is the same as you just selected BUT the billing date defaults to immediate.

Update the Billing Cycle Day

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.

Note: These steps do not change the account billing cycle day specified in the "Billing Info" section on the Account page.

  1. Open the account and click Subscriptions on the sub-menu.

  2. In the Actions column (far right), click Update BCD.

    SelectUpdateBCD

    Kaui opens the Update Subscription BCD screen:

    UpdateSubscriptionBCD

  3. In the Billing Cycle Day field, Kaui displays the currently defined BCD. Enter the number for the day of the month on which to bill.

  4. For this change to be effective immediately, leave the Effective Date field at its current setting. Otherwise, you can define a later date for this change to occur.

    Note: If Effective Date is the same as today’s date, you will not see this change take place immediately.

  5. Click the Save button. On the Account page, the Next Invoice Date is adjusted to reflect the new BCD.

Invoices

This section helps you become familiar with the Invoices and Invoice Details pages.

For more information on invoices, see the "Invoicing" section of the Subscription Guide.

Invoices Page

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.

Invoices

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.

Invoice Details Page

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

Invoice Detail

On the Invoice Details page, you can:

  • Make a payment against an invoice

  • Write off or void an invoice

  • See the payment details (if the invoice was paid)

Note: You can perform two other invoice-related tasks on the Accounts page: Generate a Dry-Run Invoice and Pay All Unpaid Invoices.

Open Invoice Details

To get to the Invoice Details page:

  1. Open an account.

  2. Click Invoices on the sub-menu.

  3. Select an invoice number.

Note: To see any associated payment details, you may need to scroll down the page.

Make a Payment on an Invoice

To make a manual payment against an invoice:

  1. Open the Invoices Details page for the invoice.

    Invoice Detail

  2. Hover over the credit card icon and select Make Payment.

    Invoice MakePayment
    Note: If the invoice has already been fully paid, the credit card icon doesn’t show, and the payment details are displayed below the invoice.

  3. Kaui displays the Process Payment screen:

    Invoice ProcessPayment

  4. Fill in the fields. For field descriptions, see Process Payment Field Descriptions.

  5. Click Save. The invoice detail shows the balance due on the invoice. Below the invoice, Kaui displays the payment details, including the status of the payment.

Process Payment Field Descriptions

Field Description

External?

Select this checkbox if the customer is making a payment outside of the Kill Bill system (such as with a check). Note that if this checkbox is selected, it overrides anything selected in the Payment Method field.

Amount

The amount defaults from the invoice balance. If the customer is making a partial payment, you can change this amount.

Payment Method

To use the account’s default payment method, leave the field blank. Otherwise, select the payment method from the drop-down.

Reason

The reason is automatically selected based on Kaui configuration settings. However, you can make a different selection.

Comment

The text you enter here displays on the Timeline page after the payment is complete. Adding comments is optional.

Write Off or Void 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:

  • Write off: Brings the balance of an unpaid invoice to $0. This method is typically used when closing an account with unpaid invoices (or when you are sure the invoice is uncollectible). When you write off an invoice, Kaui applies the WRITTEN_OFF tag to the invoice. For more information on system tags, see the "Tags" section in the Subscription Guide.

  • Void: Changes the invoice’s status to VOID, in which case it is ignored by the system. An invoice cannot be voided if:

    • It was partially or fully paid.

    • It contains positive credit items.

    • The system internally adjusted any invoice item. (In this situation, you could refund the payment before voiding the invoice.)

Write Off an Invoice

To write off an invoice:

  1. Open the Invoices Details page for the invoice.

    Invoice Detail2

  2. Hover over the tag icon i Tag. Kaui displays a drop-down:

    Invoice WriteOffDropdown

  3. Select the WRITTEN_OFF checkbox and (optionally) type text in the Comment field.

  4. Click the Update button.

    If the write-off is successful, Kaui displays "This invoice has been written off" at the top of the Invoice Detail.

Void an Invoice

To void an invoice:

  1. Open the Invoices Details page for the invoice.

    Invoice Detail3

  2. Hover over the trashcan icon i trash. Kaui displays a drop-down:

    Invoice VoidDropdown

  3. If desired, type text in the Comment field.

  4. Click the Void button.

    If the void is successful, Kaui displays "This invoice has been voided" at the top of the Invoice Detail.

Pay All Unpaid Invoices

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).

Note: If the invoices have gone unpaid because of issues with the customer’s payment method (for example, an expired credit card), make sure you delete the old payment method and add a new one.

To pay all invoices:

  1. Open the account on the Account page.

  2. In the Billing Info section, click Pay all invoices.

    PayAllInvoices

    If the payments are completed, Kaui displays a success message at the top of the screen. To see the payment details, click Payments on the sub-menu.

Generate a Dry-Run Invoice

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.

  1. Open the account on the Account page.

  2. In the Billing Info section, make sure the Dry-run checkbox is selected.

    Invoice DryRunBox

  3. In the field next to Dry-run, enter the date that matches the invoice’s upcoming invoice date.

    Invoice NextBillDate

  4. Click the magic wand button:

    i InvoiceGen

    Kaui generates and displays the draft invoice. A message at the top indicates it is a draft invoice.

Note: To change the invoice from DRAFT to COMMITTED, click "trigger an invoice run" in the message at the top of the invoice.

Payments

This section helps you become familiar with the Payments and Payment Details pages.

For more information on payments, see:

Payments Page

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.

Note: If a customer account has a default payment method, Kaui automatically makes a payment when an invoice is generated in the system. See About Automatic Invoice Payments for more information.
Payments

About Automatic Invoice Payments

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

  • Has an outstanding, unpaid invoice AND

  • Has a default and valid payment method

Kill Bill does not automatically generate an invoice payment if:

  • No default payment method exists for the account

  • The default payment method is invalid (e.g., expired credit card)

  • The AUTO_PAY_OFF or MANUAL_PAY system tags are defined for the account

Note: For invoices that Kill Bill does not automatically pay, you can use the "Pay all Invoices" feature. For more information, see Pay All Unpaid Invoices.

Payment Details Page

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.

PaymentDetails

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

Open Payment Details

To get to the Payment Details page:

  1. Open an account.

  2. Click Payments on the sub-menu.

  3. Select a payment number.

Note: To see the associated payment method information, you may need to scroll down the page.

Refund a Payment

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.

Note: You can also perform a refund directly on the payment method that was originally used. For more information, see Apply a Transaction to a Payment Method.

To refund a payment:

  1. Open the Payment Detail page for the payment.

    PaymentDetails2

  2. Hover over the credit card icon and select Refund.

    PaymentDetail SelectRefund

    Kaui opens the Process Refund screen.

    ProcessRefundPopup

  3. Fill in the fields. For field descriptions, see Process Refund Field Descriptions.

  4. Click the Save button. Kaui saves the refund and displays it as a separate row on the Payments Details page:

    PaymentDetails Refund Labeled

Process Refund Field Descriptions

Field Description

No Invoice Adjustment

Invoice Item Adjustment

If you are refunding the entire balance of the invoice, select No Invoice Adjustment. However, if you are providing a partial refund, select Invoice Item Adjustment.

Amount

The amount of the refund. Kaui automatically fills this in based on the invoice balance.

Reason

The refund reason is automatically selected based on Kaui configuration settings. However, you can make a different selection.

Comment

The text you enter here displays on the Timeline page after the payment is complete. Adding comments is optional.

Perform a Chargeback

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

  1. Open the Payment Detail page for the payment.

    PaymentDetails3

  2. Hover over the credit card icon and select Chargeback.

    PaymentDetail SelectChargeback

    Kaui opens the Process Chargeback screen with the Amount and Reason fields already filled in.

    ProcessChargeback

  3. If necessary, select a different Reason. (The chargeback reason is automatically selected based on Kaui configuration settings. However, you can make a different selection.)

  4. If the subscription associated with the payment needs to be canceled, check the Cancel account subscriptions box.

  5. Fill in the Comment field (optional). The text you enter here displays on the Timeline page.

  6. Click the Save button. Kaui saves the chargeback and displays it as a separate row on the Payments Details page:

    PaymentDetails Chargeback Labeled

Timeline

Overview

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:

TimelinePage

On the Timeline page, you can:

  • Filter events: Make selections in the Filter by event type or Filter by bundle fields to display only specific events (e.g., PURCHASE, INVOICE) and/or by a specific subscription bundle.

Timeline FilterFields

  • Sort rows: Click the up/down arrows to the right of the column header to sort by the contents of that column. The blue arrow indicates which column’s contents are currently sorted.

Timeline SortByColumn

  • Open linked documents: Click the document link in the Details column.

Timeline OpenLinkedDoc

Tenants

Overview

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

  • Software development environments (coding, testing, production, etc.)

  • Product lines (brick-and-mortar, online ecommerce, etc.)

  • Regions (north, southeast, central, etc.)

Important: If you have already created tenants using the API, you must also add them in Kaui in order for Kaui to recognize them.

Additional Tenant Resources

Create a Tenant

To create additional tenants, follow the steps below.

  1. At the top of the screen, click the gears icon i Gears and select Tenants.

    Homepage SelectGears

    Kaui displays a list of tenants on the Tenants screen:

    TenantsList

  2. Click the plus sign i PlusGreen next to Kaui Tenants.

    Kaui displays the Add New Tenant screen:

    AddNewTenant

  3. Enter the tenant Name, API Key, and API Secret.

    Note: The API key and API secret pair are used in all HTTP requests to ensure that the user issuing the request has the correct permissions to access the tenant.

  4. Click the Save button.

    Kaui displays the Tenant Configuration page with the new tenant name in the upper right corner:

    TenantConfig TenantName

Tenant Configuration Page

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

TenantConfig Labeled

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 i PlusGreen 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:

  • Catalog Show—Create and manage catalog XML files.

  • Overdue Show—Create and manage the XML configuration file that helps to control Kill Bill’s overdue (dunning) functionality.

  • Invoice Template—Upload invoice template files.

  • Invoice Translation—Upload translated invoice files.

  • Catalog Translation—Upload translated catalog strings files.

  • Plugin Config—Upload plugin configuration files. Currently undocumented.

Add an Allowed User to the 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.

  1. Click on your username and tenant name in the upper right corner:

    Users SelectTenantName

    Kaui displays the Tenant Configuration page.

  2. To the right of Allowed Users, click the plus icon i PlusGreen.

    UserTenantScreen2

    Kaui displays the Add Allowed User pop-up.

    AddAllowedUser

  3. Type the user name into the User name field.

  4. Click the Add button.

    Kaui displays the newly added user to the Allowed Users list for the tenant.

Remove a User from the Tenant

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.

Warning: Deleting the admin user for a tenant means will remove administrative access to the tenant.

  1. Click on your username and tenant name in the upper right corner:

    Users SelectTenantName

    Kaui displays the Tenant Configuration page.

  2. In the Allowed Users section, click the black X to the right of the user to remove:

    UserTenantScreen3

  3. Click OK to confirm the deletion.

Users, Roles, and Permissions

Overview

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:

  • The user’s roles (i.e., permissions in the system)

  • The tenants the user can access

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

  • Creating user roles

  • Creating and editing users

  • Assigning roles and tenants to users

Before You Begin

Before you begin working with users, make sure that:

  • You can log in as a Kaui admin. OR

  • You can log in as a user with the correct permissions for working with users, roles, and permissions.

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

Additional Resources

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

Managing Users with a Third-Party System

If your organization uses a third-party system, such as LDAP, Okta, or Auth0, to manage Kill Bill users and roles, first configure them in that system, then add them in Kaui. For more information, see Users, Roles, and Permissions Management.

In Kaui, all that’s required is to add the username per the Add a User section, then edit the user profile to define passwords and roles.

Managing Users with Kill Bill

If you are using the Kill Bill database to store user data, adding a user profile in Kaui automatically creates it in Kill Bill.

Create a User Role

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:

  1. Open the Add New Role Definition screen, either from the User Update screen (see Edit a User) or by accessing https://<your_host>/kaui/role_definitions/new.

    AddNewRole

  2. Enter the Role name for the user. Do not use any spaces in the role name.

  3. Enter all the Permissions that are associated with this role. See the list of Kill Bill user permissions as a reference.

  4. Click the Save button.

Open the User List

To open a list of Kaui users:

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

Homepage SelectGears

Kaui displays the Users screen:

UsersList3

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.

Add a User

  1. Open the users list.

  2. Select the plus icon i PlusGreen next to Kaui Users.

    Kaui displays the Add New User pop-up:

    AddNewUser

  3. Fill in the user fields. For field descriptions, see Add New User Field Descriptions.

  4. Click the Save button. Kaui displays the Configured Tenants pop-up:

    ConfiguredTenants3

  5. Select the tenant(s) the user has access to.

  6. Click the Save button.

Edit a User

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

  1. Open the user list.

    UsersList3

  2. Select the user you want to edit.

    Kaui displays the User Details screen with the user’s allowed tenants below.

    ConfiguredTenants2

  3. To edit the tenant, select or deselect the appropriate boxes and click the Save button.

  4. To edit other user information, click Edit (next to User Details).

    Kaui displays the Update User screen:

    UpdateUser

  5. Fill in the user fields. For field descriptions, see Add a New User Field Descriptions.

  6. Click the Save button.

Add New User Field Descriptions

Field Description

Managed externally (LDAP, Okta, etc.)?

Check this box if you are managing users in a third-party system. Otherwise, leave it unchecked.

Name

Enter the user’s name.

Password

Enter the user’s password. For security, Kaui does not display any existing passwords in this field, but you can type in a different one. It may be easier to copy and paste the password into this field.

Description

To provide a brief description of this user or his/her role, type it here. Kaui displays this description on the Allowed Users list on the Tenant screen.

Roles

Enter the roles that are associated with this user. You also have the option to create a new role.

Delete a User

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.

  1. Open the user list.

    UsersList3

  2. Select the user you want to delete.

    Kaui displays the User Details screen (with the user’s allowed tenants below).

    ConfiguredTenants2

  3. Click the i RedX icon. Kaui displays a message to confirm the deletion.

  4. Click OK.

  5. Kaui displays the login screen and asks you to confirm your login credentials.

    After you successfully log in, Kaui deletes the user.

Catalog

Overview

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.

Additional Catalog Resources

View Catalog Products and Plans

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:

  1. Click on your username and tenant name in the upper right corner:

    Users SelectTenantName

    Kaui displays the Tenant Configuration page.

  2. Scroll down until you see the Catalog Show tab:

    Catalog Tabs ShowCat

Create a Simple Catalog

  1. Go to the Catalog Show tab on the Tenant Configuration page.

    Catalog Tabs ShowCat

  2. Click the plus sign i PlusGreen next to Existing Plans.

    Kaui opens the Catalog Configuration screen:

    CatalogConfiguration

  3. Fill in the fields. For field descriptions, see Catalog Configuration Field Descriptions.

  4. Click the Save button.

Catalog Configuration Field Descriptions

For additional field information, see the Catalog API.

Field Description

Product Category

Define whether this product is of the BASE, ADDON, or STANDALONE category:

  • Base products can have one or more addons.

  • Add-on products can be bundled with a base product.

  • Standalone products cannot have any add-ons.

Product Name

The name assigned to the product you are selling.

Plan Name

The name of the plan, which defines how the product will be sold (for example, a monthly subscription or a one-time purchase).

Amount

The price of the plan to be paid every billing period.

Currency

The currency this plan uses. If you need to add more currencies, you can do so by adding a currency to a plan.

Billing Period

The period for which the customer is billed.

Trial Length

Along with a unit of time (Trial Time Unit below), defines the length of the trial.

Trial Time Unit

Along with the Trial Length number above, specifies the time interval for the trial.

Add a Currency to a Plan

  1. Go to the Catalog Show tab on the Tenant Configuration page.

    Catalog Tabs ShowCat

  2. On the row of the plan for which you want to add a currency, click + currency on the far right.

    Kaui displays the Add Plan Currency screen:

    Catalog AddPlanCurrency

  3. Fill in the fields:

    • Plan ID—By default, Kaui fills in this field based on the plan you selected, but you can change it to a different plan ID.

    • Amount—The cost of the plan in the new currency you’re adding.

    • Currency—The currency you are adding.

  4. Click the Save button. Kaui displays the new currency on the Catalog Show tab.

Upload an XML Catalog

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

Note: You cannot edit a raw XML catalog in Kaui.

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.

Note: To ensure a successful catalog file upload, check its validity with the Kill Bill catalog validation tool.

To upload an XML catalog in Kaui:

  1. Go to the Catalog Show tab on the Tenant Configuration page.

    Catalog Tabs ShowCat

  2. Click the plus sign i PlusGreen next to Existing Plans.

    Kaui opens the Catalog Configuration screen:

    CatalogConfiguration

  3. Click on Enable Advanced Configuration (Upload XML).

    Kaui displays an upload screen:

    Catalog AdvancedConfigUpload

  4. Click the Choose File button, locate the XML file, and select it.

    Once you have selected the file, Kaui displays the filename next to the Choose File button.

    Catalog AdvancedConfigUpload File

  5. Click the Upload button.

    If the upload is successful, Kaui displays a confirmation message along with a list of plans on the Catalog Show tab:

    Catalog UploadSuccess
Note: If you receive an "Invalid catalog for tenant" error, run the catalog through the Kill Bill catalog validation tool (if you haven’t already). You can also delete the existing catalog and retry the upload steps.

View the Catalog as XML

  1. Go to the Catalog Show tab on the Tenant Configuration page.

    Catalog Tabs ShowCat

  2. Click Enable XML View.

    Kaui displays the list of catalog versions:

    Catalog ListOfVersions

  3. Click view xml. Kaui displays the raw XML (you cannot edit in this view).

    Catalog RawXML

  4. To return to Kaui, click the Back arrow button of your browser.

Delete a Catalog

  1. Go to the Catalog Show tab on the Tenant Configuration page.

    Catalog Tabs ShowCat

  2. Click the red X to the left of Enable XML View.

    Kaui removes the plans from the Catalog Show tab and displays a successful deletion message.

Download the Catalog

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

  1. Go to the Catalog Show tab on the Tenant Configuration page.

    Catalog Tabs ShowCat

  2. Click the down arrow i GreenDownloadArrow.

    Catalog Download

    Kaui downloads the .xml file to your default download folder on your local drive.

Overdue

Overview

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

  • The various states that the account must go through

  • The change in users' entitlements when the account is transitioned from one state to the other

  • The period after which the state is re-evaluated

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:

Additional Overdue Resources

View Overdue Configuration

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:

  1. Click on your username and tenant name in the upper right corner:

    Users SelectTenantName

    Kaui displays the Tenant Configuration page.

  2. Scroll down and click on the Overdue Show tab:

    OverdueTab

Create Overdue Flows

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

  1. Go to the Overdue Show tab on the Tenant Configuration page.

    OverdueTab

  2. Click the plus sign i PlusGreen next to Existing Overdue Config.

    Kaui opens the Overdue Configuration screen:

    OverdueConfig Empty

  3. Click + New Overdue States. Kaui opens the fields for editing:

    OverdueConfig BlankFields

  4. Fill in the fields for the current row. For field information, see the Overdue Configuration Field Descriptions table.

  5. To add another overdue configuration row, click + new overdue states.

    Overdue Select NewOverdueState

  6. When you are done adding configuration rows, click the Save button. Kaui displays a success message at the top of the screen and displays the new overdue flow(s) on the Overdue Show tab.

    Overdue ShowFlows
Note: To edit an existing overdue flow, on the Overdue Show tab, click the plus sign i PlusGreen next to Existing Overdue Config. This opens the overdue configuration fields in edit mode.

Overdue Configuration Field Descriptions

Field Description

Name

The name assigned to the overdue state.

External Message

Message text that other plugins, when listening for overdue events, can retrieve and display to the user. (Optional)

Block Subscription Changes

If set to true, the customer cannot make plan changes to the subscription in this overdue flow. If set to false, the customer is allowed to make changes.

Subscription Cancellation

Select the option that describes how Kill Bill behaves regarding a cancellation in this overdue flow:

  • NONE: Kill Bill ignores this field, and the subscription is not cancelled.

  • POLICY_NONE: Same as NONE above.

  • POLICY_IMMEDIATE_POLICY: Cancels the subscription immediately and applies a partial credit to the account based on how much of the service has been consumed.

  • POLICY_END_OF_TERM: Cancels the subscription at the end of the billing period with no refund to the customer (i.e., no proration).

Days Since Earliest Unpaid Invoice

Specifies how many days should pass after the last unpaid invoice before initiating this overdue flow.

Tag Inclusion

Specifies that the overdue flow will occur if the account has a system (control) tag matching the one selected here. To disregard tag inclusion for this overdue flow, leave as the default NONE setting.

  • AUTO_PAY_OFF

  • AUTO_INVOICING_OFF

  • OVERDUE_ENFORCEMENT_OFF

  • MANUAL_PAY

  • TEST

  • PARTNER

For a description of system tags, see the "Tags" section of the Subscription Guide.

Tag Exclusion

Specifies that overdue flow will occur if the account has NO system (control) tags matching the one selected here. To disregard tag exclusion for this overdue flow, leave as the default NONE setting.

Number of Unpaid Invoices

Specifies that the overdue flow will occur if the number of unpaid invoices equals or exceeds the specified value.

Total Unpaid Invoice Balance

Specifies that the overdue action will occur if the total unpaid invoice balance equals or exceeds the specified value.

Upload an XML Overdue Configuration File

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

Note: You cannot edit a raw overdue configuration XML file in Kaui.

  1. Go to the Overdue Show tab on the Tenant Configuration page.

    OverdueTab

  2. Click the plus sign i PlusGreen next to Existing Overdue Config.

    Kaui opens the Overdue Configuration screen:

    OverdueConfig Empty

  3. Click Enable Advanced Configuration (Upload XML). Kaui displays an upload screen:

    Overdue AdvancedConfigUpload

  4. Click the Choose File button, locate the XML file, and select it.

    Once you have selected the file, Kaui displays the filename next to the Choose File button.

    Overdue AdvancedConfigUpload File

  5. Click the Upload button.

    If the upload is successful, Kaui displays a success message at the top of the screen and displays the overdue flow(s) on the Overdue Show tab.

    Overdue ShowUpload

View Overdue Configuration as XML

  1. Go to the Overdue Show tab on the Tenant Configuration page.

    OverdueTab

  2. Click View Overdue XML to the right of the plus sign i PlusGreen. Kaui displays the raw XML (you cannot edit in this view).

  3. To return to Kaui, click the Back arrow button of your browser.

Delete Overdue Flows

  1. Go to the Overdue Show tab on the Tenant Configuration page.

    OverdueTab

  2. Click the plus sign i PlusGreen next to Existing Overdue Config.

    Kaui opens the Overdue Configuration screen.

  3. Click the red X to the right of every configuration row you want to delete.

    Overdue Select Delete

  4. Click the Save button.

    Kaui removes the overdue configuration row(s) from the Overdue Show tab and displays a delete confirmation message.

Translation Files

Overview

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:

  • Invoice Template

  • Invoice Translation

  • Catalog Translation

TranslationFilesTabs

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

Additional Translation Resources

View Translation Tabs

To get there:

  1. Click on your username and tenant name in the upper right corner:

    Users SelectTenantName

    Kaui displays the Tenant Configuration page.

  2. Scroll down to see the translation tabs:

    TranslationFilesTabs

Upload a Translation File

  1. Go to the Tenant Configuration page and scroll down to the translation tabs.

  2. Select the appropriate translation tab for the file you want to upload.

  3. Click the Choose File button, locate the translation file, and select it.

    Once you have selected the file, Kaui displays the filename next to the Choose File button.

    Translation UploadInvTemplate

  4. For Invoice Templates only: If this invoice template supports the manual pay option (for accounts that have the MANUAL_PAY tag), select the Manual Pay checkbox. (For more information, see the "Templates" section of the API.)

    Translation UploadInvTemplate Manual

  5. For Invoice Translation and Catalog Translation only: In the Locale field, specify the language supported by the uploaded file using the ISO country_language format.

    Translation UploadInvTransFile

  6. Click the Upload button.

    If the upload is successful, Kaui displays a success message at the top of the screen and lists the file on the tab.

Tags

Overview

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.

Note: You can use the API to attach tags to even more object types, such as payments and subscriptions. For more information, see the "Tags" section of the relevant object type section (for example, Payments) in the API Reference.

Types of Tags

Kill Bill has two types of tags:

  • Control tags—Also referred to as system tags, these tags modify the behavior of the system. Kill Bill includes several control tags; see the API documentation for a list.

  • User tags—These tags are not interpreted by Kill Bill; they are a way for admins or third-party systems to annotate specific existing resources. For instance, the support team could tag account resources associated with a specific customer to group them.

Note: Kill Bill does not include default user tags.

You can view all available tags on the Tag Definitions page.

About Tag Definitions

In order to use a user tag in Kill Bill, you must first create its tag definition. As its name implies, a tag definition defines information about a specific tag. In Kaui, you must create a tag definition for a user tag before you can attach it to an account or invoice.

Note: You cannot add, change, or delete the underlying tag definition for control tags.

Additional Tag Resources

API Reference:

View All Tags

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:

TagDropdown TagDef

Kaui displays the Tag Definitions page.

TagDefinitionsPage

View Objects with Attached Tags

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:

TagDropdown Tags

Kaui displays the Tags page.

TagsPage All
Tip: On the Tags page, you can open the object (account, invoice, etc.) by clicking the link in the Object ID column.

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

  1. Open the account on the Account page.

  2. Click Tags on the sub-menu.

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

TagsPage

Add a Tag Definition

To create a new tag definition:

  1. Open the Tag Definitions page as explain in "View All Tags."

    TagDefinitionsPage

  2. Next to Tag Definitions, click the plus sign i PlusGreen.

    Kaui displays the Add New Tag Definition screen:

    AddTagDefinition

  3. Fill in the fields:

    • Object type—The type of object that the tag can be attached to (for example, accounts). To allow this tag to be applied to other object types, click the plus sign icon i PlusGreen next to Object type.

    • Name—The name of the tag.

    • Description—Text that describes how the tag is used. Kaui will show this text on the Tag Definitions page.

  4. Click the Save button. Kaui displays the new tag definition on the Tag Definitions page.

    TagDefinition AfterCreate

Delete a Tag Definition

Warning: Kaui does not ask you to confirm your deletion; use this feature with caution.

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:

  1. Open the Tag Definitions page as explain in "View All Tags".

    TagDefinition AfterCreate

  2. On the tag definition row, click Destroy.

Attach or Remove a Tag

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.

  1. Open the account on the Accounts page.

  2. Click the tag icon:

    Account ShowTags

  3. To attach a tag, select its checkbox. You can select more than one checkbox to attach multiple tags.

    To remove a tag, click the box to clear it.

  4. If you’re attaching a tag, you can optionally add text in the Comment field. Kill Bill stores the Comment text in the tags audit log (accessible via API).

  5. Click the Update button.

Custom Fields

Overview

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.

Note: Kill Bill does not include default custom fields.

Additional Custom Tag Resources

View All Custom Fields

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.

TagDropdown CustomFields

Kaui displays the Custom Fields page:

CustomFields More
Tip: On the Custom Fields page, you can open the object (account, invoice, etc.) by clicking the link in the Object ID column.

View Custom Fields for an Account

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).

  1. Open the account on the Account page.

  2. Click Custom Fields on the sub-menu.

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

CustomFields Specific

Create and Attach a Custom Field

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

  1. Open the Custom Fields page as explain in "View All Custom Fields".

    CustomFields Populated

  2. Click the plus sign i PlusGreen next to Custom Fields.

    Kaui displays the Add New Custom Field screen:

    AddNewCustomField

  3. Fill in the fields. For field descriptions, see Custom Field Descriptions.

  4. Click the Save button. Kaui displays the new custom field on the Custom Fields page.

CustomFields More

Custom Field Descriptions

Field Description

Object ID

The identifier of the object to which you want to attach a custom field.

Note: To copy the identifier for the object, open a separate browser tab and copy the ID from the URL displayed on your browser’s address line:

Example:

URL: https://demo.killbill.io/accounts/1033706a-07de-4ed3-b0e0-0f1d09639b90/invoices/421d16de-6d19-41a0-b9e5-781ab3eedf1c

Invoice ID: 421d16de-6d19-41a0-b9e5-781ab3eedf1c

Object type

The type of object that the custom field is being attached to, such as an account or payment.

Name

The name of the custom field (Example: Level).

Value

The value associated with this custom field (Example: Medium).

Plugin Manager

Overview

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:

Install a Plugin

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

  1. Click on the plugin icon at the top and select kpm.

    kpm install

  2. Click on Install New Plugin.

  3. Click on the download icon next to the plugin that you wish to install.

  4. Wait a few minutes, then refresh the web page.

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

Analytics

Overview

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:

analytics mrr

For more information, see the Analytics Guide.