Getting Started with jBilling

The Enterprise Open Source Billing System

Getting Started Guide

Welcome

Welcome to jBilling! With thousands of users across the world and a mature product, jBilling is the leader in billing automation. jBilling has been in production for many years, generating invoices and processing payments for companies of all sizes.

Choosing jBilling will save you time and will allow your company to grow. Invoice generation following complex business rules and taxes, customer self-care through its web-based interface and automatic payment processing are only some of the jBilling's time-saving features.

Getting jBilling all setup and ready to run is not without effort. Are you going to accept credit cards? How often are your customers going to get invoices? How are they going to receive these invoices? By email, in the mail? How much time can a customer take to pay an invoice? What happens if a customer doesn't pay? You know the answers to these questions, now we need to let jBilling know so it can run your billing following your business rules.

You can start by taking a look to the example company 'Trend', which is included with the standard jBilling download. Login using the user name 'admin', password '123qwe' and company ID 1. You will find the steps that this guide will walk you through already done: there are customers and invoices, among other example data. The idea is for you to create a new company to start from scratch, and then follow this guide step by step as a tutorial.

Once you are done with this guide, you can move on to the next Getting Started guide. It covers the usage of rules for rating, complex pricing and item relationship management through a Business Rules Management System (BRMS).

Get yourself a cup of hot chocolate and some patience and keep reading. Running jBilling is well worth the effort.

Entering your customer's data

We'll start by entering the basic data that a billing system needs, which is who your customers are, and what it is that they have bought. This is an overview of the data we need to enter:

Items: Represent the catalog of goods or services your company sells.
Item categories: These are groups of items
Customers: These people buy from you, and pay!
Purchase orders: A customer's subscription or purchase from your company is represented in jBilling by 'purchase orders'.
Order periods: Here you configure how often your customers receive an invoice.

Let's take a look at how these data elements interact:

The items represent the products and services that your company offers. Items are bought by your customers by placing purchase orders. Periodically, a batch process called ‘billing process’ will run and generate invoices based on these purchase orders. The invoices will then be paid by your customers by submitting payments, or the system can automatically process these payments through its automatic payment processing feature.

It's time to start entering your data. Since it is always better to explain with an example, we'll use the fictitious company 'Trend', which sells advertisement on its popular website.

Item categories

An item needs to belong to at least one category and that is why item categories is the very first thing we need to enter. Item categories are also referred in jBilling as 'item types'. Categories help to group items, and this grouping will be helpful later on for running a report or for invoice calculations. For example, you might want to know how much you have invoiced your customers for a given month, excluding taxes. You can create as many categories as you want.

For Trend, we will create the category 'Banners'. Click on Items, then Types. On the left menu, click on Create Type. Enter the category name, 'Banners' and the type 'Items'. The category type lets jBilling know how to treat the items that belong to this category. A regular item should belong to a category of type 'Items'.

Items

For the most part, items are the catalog of product and services your company sells. There are other factors affecting how much your customers pay you, such as taxes and discounts. These too have to be represented as items in jBilling.

For Trend, we will create the 'Front page banner' item, that will represent a one month charge for having a banner ad in Trend's front page. Click on Items then on Create The item form is displayed, with a number of fields. For the description, we enter 'Front page banner – monthly fee', for category we select 'Banners' and for price we enter 100.

Let's briefly go over some of the item's attributes:

Number: It is a way to identify the item. Items will be ordered using this number in an invoice.
Percentage: Useful for representing a value calculated as a percentage of the total, such as a value added tax.
Price: A flat number being the cost of one unit of this item. You can enter the price in many currencies if you have configured the system for multiple currencies.

There are more attributes and more to say about the above, which is all covered in jBilling's user guide.

Customers

Now that we have something to sell, let's enter the information regarding the buyers. Click on Users then on Customers. This will display the list of customers, which is empty right now. Click on New on the left menu to enter a new customer.

This initial form will have the basic information about a customer. The login name and the password are to allow the user to access jBilling to review her invoice, submit payments and other customer self-care operations. The email is very important because jBilling can notify your customers of many billing related events, such as when a new invoice is ready, a payment has been processed, when one is late with their payments, etc.

For Trend, we'll enter 'jsmith' as login name, 'secret12' for password (same thing in 'repeat password') and jsmith@acme.com for the email address. Clicking on 'Submit' will create the customer. More information about this customer, such as the address and credit card information, can be entered immediately after, by clicking on the links on the left.

Order periods

Now it is time to define how often your customers will be billed, and therefore, how often they should pay. Another way of viewing this is what type of subscriptions will be available for your customers. We need to define the order periods now because it is required before the next step, which is creating a purchase order.

The most common period is monthly. It seems that we are used to paying for services on a monthly basis. jBilling can handle any number of days, weeks months or years as an order period. Also, the 'one-time' order period represents a purchase that does not recur. This last period is always there by default, so you don't need to create it.

We will create two periods for Trend, a Monthly one and another one for 3 month periods. Click on Orders then on Periods. For value enter '1', the unit will be 'Month' and the description 'Monthly'. Click on Submit to confirm. To add another period, click on 'Add a new order period' and then enter '3' for value, the unit will be 'Month' again and the description 'Quarterly'.

Purchase orders

We are ready for sales, now that we have customers and something to sale to them. Purchase orders in jBilling represent sales. This could be a one-time purchase or a subscription into which the customer pays regularly. You can think of a purchase order as a bag with many items that a customer buys, let's create one for Trend. The customer Jenny Smith just bought a subscription to have her company's ad on the front page. She is going to pay monthly for this service.

Click on Orders and then on Create. Now you have to select a customer that is getting a new order, click on 'jsmith'. For the period, select 'Monthly', since this order will produce one invoice per month. Trend gets paid in advance for its advertising services, therefore the type is 'pre paid'. This field answers the question: do you deliver your services first, and then get paid (post paid), or your customers pay first and then get your services (pre paid). We will leave all the other fields blank for now and click on 'Continue'.

The list of item is now displayed. You can now select which items are going to be included in this order. We only have one now, so click on 'Add' and then on Review (left side of the screen). The review screen allows us to take a final look at the order before creating it. At this point it is possible to change the description of the item. This field is initially populated by the description of the item, but now we can change this to whatever we want. For example, we might have a generic item called 'Banners'; but for each order created we can add some information about this particular sale in the description field. The 'Banner' can then be 'Banner – front page - animated'. Click on 'Submit Order' to finish.

This is all we need to do to subscribe a customer to a service. It is really just a few clicks, because all the customer and item information is already there.

Adding more orders

Let's now explore some variations on the same example. Trend now charges an 'account maintenance fee' which is charged to all customers every three months. How do we add this to Jenny Smith? First, we need to create the item, just the same way it was explained in the previous section. Then we need a new order, similar to the first one but with the period being 'Quarterly' and, of course, with a different item.

So we have two orders for this customer, one that is monthly and one that is quarterly. Jenny Smith will receive only one invoice per month. For January she'll see two lines in her invoice, one for the banner subscription plus the maintenance fee. The February and March will go with just the banner item in her invoice. April's invoice will be the same as January. A customer can have multiple orders. The billing process will produce invoices by combining the orders.

Another variation: our customer takes advantage of Trend's graphic designing services. This is a one time purchase that should be included in her next invoice. No problem, we just need to create a new order, in the same manner we've been doing but with a 'one time' period. This order will include its items in the next invoice and will not participate in any further invoicing. It does not recur.

Generating an invoice

Once we have entered all our customers and their purchase orders, we still do not have any invoices. So, how are they generated in jBilling? There are two ways:

Billing process: This is the recommended way to generate invoices. It is an automated process that runs periodically, going through all the orders and generating invoices only when necessary. You will find details about how to configure the billing process later in this guide.
Manually: From a purchase order, you can click on the left menu option 'Generate invoice and payment'. This will create an invoice out of the selected order. This is not the way to generate the bulk of your invoices, but it is helpful when you want to create an invoice immediately, instead of waiting for the next billing process to run.

In any case, you never create an invoice line by line with arbitrary values. Invoices always get created from purchase orders. You can always trace an invoice to its originating purchase order. It is a way of saying, “you will only bill a customer if that customer first bought something from you”. In the same line, you never modify an invoice directly. You could delete the invoice, change the order and generate the invoice again. The idea is to have a consistent model where you can trace documents and the reasons for their existence.

More scenarios

We've only covered a very simple scenario so far, and you might be wondering if other scenarios common in your company can be addressed with jBilling. It is actually very hard to come up with a billing scenario that jBilling cannot handle. It is all about the good handling of items and orders, which is covered in detail in jBilling's users guide.

Following is a list of a few common billing scenarios, with some tips to get you started:

Scenario	Example	Tips
Group your customers so each group gets invoiced on a different day.	You divide you customers in two groups, one getting invoiced on the 1^st day, and the other one on the 15^th day of every month.	Set your billing process to run every 15 days, and separate your customers into two groups by creating the initial purchase orders with two different dates in the 'active since' field.
Customers can buy subscriptions at any time. Do we prorate until the end of the month?	Your services are billed monthly, but a subscriber just joined on the 15^th.	Create orders normally, leaving the 'active since' field empty. Run a billing process daily, so a customer joining on the 15^th will be billed on the 15^th of every month. There is no prorate calculations and the billing is accurate. This is more simple for you and your customers.
There are many subscriptions periods.	You sell monthly, quarterly and yearly subscriptions to your services. Every customer then can be different.	Create as many order periods as types of subscriptions, then simply create the purchase order for each customer with the right period.
Trial (free) period, followed by automatic subscription.	You sell your subscriptions with an initial period of 15 days free. After that, if the customer doesn't cancel, she gets billed monthly at the regular price.	Create your purchase orders with and 'active since' equal to today's date plus 15 days. If the customer cancels, you have to delete the order (best done with web services for full automation)
Assign customers a billing cycle, with pro-rating for the first period of new subscriptions. All the orders should be aligned to the customer's billing cycle date.	A customer signs-up for a set of monthly services on the 10^th of the month. She should receive one invoice every 10^th of the month, but she might subscribe (or unsubscribe) to some of the services any other day of the month. This new subscriptions should align with the main order, and pro-rate the first period to the days between the sign-up date and the next invoice.	You need to use the 'cycle start' property of the orders to align them to a single date. jBilling will calculate the pro-rated amount for the first period. This applies also to cancellations that leave only part of a period left to invoice. Note: Pro-rating is not activated by default. Refer to the User Guide for instructions on how to configure jBilling to do pro-rating.

System configuration

The data alone is not enough to run your billing. We also have to tell jBilling about the billing process itself and other system-wide parameters. We are not going to get into the details of all these parameters, but we are going to configure jBilling to run Trend's billing. Trend has chosen to have its billing run on the first of every month. A few days before the billing run, the billing department would like to be able to review the invoices about to be sent out. Once ready and reviewed, the invoices need to be forwarded to customers using e-mail.

Since most of its clients pay by using credit cards or direct debit, Trend expects the system to retry payments that have failed. For example, the billing run happens on the first of the month. For any payment that did not go through, the system should try processing the payment once more on the 5^th of the month and again on the 10^th, should the second attempt be fruitless. Ideally, jBilling should notify by e-mail any late payer up to 3 times over a set period of time, reminding them that their account carries an overdue balance.

Notifications

jBilling will notify your customers about various events, the most important one being most likely any new invoice. By default, these notifications have text that might not suit your company, so it is very important that you review and edit the text for those that you will be using. You may also decide that you do not want some of the notifications to be sent at all.

Let’s start by getting a list of all the notifications that you can configure by clicking Notification. These are all email notifications except ‘Invoice (paper)’. Once you click on an email notification, you will see two text boxes. The first one represents the subject of the email; the second one is the body of the email.

You will have to go through each of the notifications in this list and decide if you want the notification to be sent, and if so, review the text.

Email Delivery Parameters

jBilling will send emails to your customers on your behalf for many reasons. Sending them their invoices is one, but but also reminders, failure to receive a payment, balance overdue, etc. You could opt out of sending any emails, but consider that this service is totally free for you and, once well configured, will take none of your time.

jBilling needs to know about a mail server in order to send emails. Click on Notification and then on Parameters. Here you have to enter your mail server information. Ask your system administrator or your ISP provider for these values.

Invoice Reminders

This feature’s purpose is to remind your customers that an invoice had been sent to them. When this option is selected, one or several e-mails will automatically be sent to your customers at intervals that you will have previously chosen. They will be sent after an invoice has been generated and until that invoice is paid or reaches its due date (whichever comes first).

Click on Notification and then on Preferences. The bottom three fields are related to invoice reminders.

The Aging process

What happens when a customer hasn’t paid and the due date has come and past? This is the issue addressed by the Ageing process. The term ‘Ageing’ is used to reflect the several steps that a customer's account goes through, starting with ‘Active’ and ending with ‘Deleted’. This process notifies your customers about their overdue invoices, and changes the status of that customer’s account. Go to the Ageing configuration screen by clicking on System and then Aging.

In our Trend example, we enter a Grace Period of 5 days, so no action will be taken the first 5 days after the due date of an invoice. Trend switches on 3 steps in the aging process: with 7 days, Overdue 2 with 10 days and Overdue 3 with 0 days. The end result is one notification after 5 days an invoice going overdue, followed by another one after 7 more days, and the last one 10 days later.

The billing process

The billing process is the batch process that will generate invoices. Having a good understanding of what it does is important. You will have to configure a few simple parameters found under the options Process and then Configuration.

Trend wants to run its billing on the first of each month, so for 'Next Run Date' it will enter the first day of the next month. This field will be automatically updated by the billing process when it runs, adding one month. Since the process is ran only once per month (the shortest order period for

Trendis one month) we enter '1 Month' for the 'Billing Period' field.

Trend's wants to verify the results of the billing process three days before it actually happens, so it selects the check box 'Generate Review Report'. Then it adds a 3 for the 'Review reports days.

To achieve the payment retries set at the beginning of this section, we'll need to enter a 2 for the 'Number of Retries' and a 5 for the 'Number of days between retries'.

Invoice Numbering

jBilling will apply the number 1 to your first invoice generated. If, however, your company has generated previous invoices, it is necessary to tell the system about this number so it can properly number the next invoices.

To configure the number of your first invoice, and perhaps the prefix to your invoices, click on Invoice, then on Numbering.

Payment Processors

A payment processor is a service, provided by a company dedicated to this, that allows your company to receive payments with instruments such as a credit cards, direct debit from bank accounts, etc. Some of these payment processors also let you to electronically submit transactions from, a billing system such as jBilling. This is a powerful concept: when jBilling runs the billing process, it can also get the generated invoices automatically paid with your customer's credit cards or banking information. This allows for a several other automation features: payment retries, notification to your customers about the results of their payments (usually via email), etc.

The problem is that each payment processor has its own API. In plain English, each payment processor talks a different language so we need an 'interface' for each of them. Right now, jBilling only supports one payment processor: authorize.net. Creating new interfaces to support other payment processors is not difficult, but it requires the development of a plug-in which is out of the scope of this guide.

Thus, this section only applies if you plan on using automatic payment processing (usually with credit cards) and have an account with authorize.net.

Click on System and then on Plug-ins. A list of the current plug-ins will be displayed. At the bottom of the screen, you will see the link 'Add a new Plug-In'. Click on it. On the newly added task, click on the drop down field and select 'com....PaymentAuthorizeNetTask'. Then click on the button 'Submit' to finish creating the new plug-in.

Now we need to add two parameters to this plug-in. These are the credentials given to you to identify your account in authorize.net. Click on the link 'Add parameter', immediately below the new task you've added. Change 'parameter_name' to 'login' and 'default' to your login name, then click on 'Submit'. Repeat the process to add another parameter, this time using 'transaction' for the parameter name, and your transaction key as value (how to get the transaction key of your account, is described in authorize.net's documentation).

That's all. jBilling knows that you want to use authorize.net as a payment processor and how to communicate with it, so it will be able to use it for any automatic payment processing.

Tutorial: My first invoice

Now jBilling is configured and ready to use. Let's go through the steps of creating one manual invoice. This is going to be just one simple example to get familiar with jBilling's user interface. To follow the theme of this guide, we'll assume that there is a new customer that has just bought 6 months of front page advertising. Before starting, make sure you already have the item already entered, as explained in the 'items' section above.

Create the new customer record

You may do this right after you login to jBilling by clicking on the link 'Create new customer', or by clicking on User, then Customer and on New. In the form you can enter the new customer's user name and password. You should pass on this information to the customer so she is later allowed to log in to jBilling and review her invoices, submit a payment, update her contact information, etc. The email address is also important as that is where jBilling will send notifications such as invoice, payment confirmations, reminders, etc. Click on 'Submit' to create the user.

Once this is done, you will have a customer record, although you still want to enter a credit card number as well as the customer's address. Click on 'Edit this user's contact information' and enter the mailing address. This address will be used later on to generate PDF invoices. Now click on 'Edit this user's credit card information'. The credit card will be used to get the invoices paid automatically as soon as they are generated.

One last change. You want this customer to get her invoices in two ways: as an immediate email and as a mailed printed paper invoice. The first one will give her a 'heads up' while the second one will be a more official way of stating the charge. To reflect this, click on the drop-down menu of the 'Invoice delivery method' field and select 'Email + Paper'.

Create the order

To create an order, you can click on the link 'Create a purchase order for this user'. This link is on the right side of the screen and it shorter than clicking on Orders, then on Create and then selecting the customer you've just created.

Either way, you'll find a form with the order's main fields. Select a Monthly period, with a 'pre-paid' type, so that an invoice is generated in advance of each month. Leave the 'active since' blank, because the order is active immediately and this field takes today as a default. For the 'active until' enter 10/15/2000, assuming that today is 4/15/2000. This means that the order will be active for six months, starting now. Click on 'Continue'.

We are now presented with a list of items. Click on 'Add' for the item 'Front page banner – monthly fee', then click on Review on the left side of the screen.

The review screen is straight forward in this case. Just click on 'Submit Order' to complete the order creation.

Generate the invoice

The order is ready, which allow you to create the first invoice. For this example, you will manually trigger the invoice generation. This is not a requirement and in many cases it is not the recommended way to generate an invoice. If you leave the order the way it is, the next billing process will generate the invoice for you. In this example, you want the invoice right now and can't wait.

Click on the link 'Generate invoice and payment'. This will create the invoice and take you to a payment screen where you can get the new invoice paid. Since you don't want that right now, simply click on the invoice ID number to go straight to the invoice review page.

Review the invoice

manually trigger details. Review the date, due date, total and invoice lines to make sure it is all correct. If something is wrong, you will have to delete the invoice (see the link on the left), modify the order and generate the invoice again.

In our example, let's assume that the invoice is correct. It is Trend's policy to notify the customer for every invoice created. Thus, click on the link 'Click here to send an email notification with this invoice'.

Pay the invoice

Last but not least, we want this first invoice paid. Trend's services are pre-paid after all and so is the order that we created. Click on Payments Credit Card. Select the new customer from the list.

In the payments form, there is a list containing the customer's invoices with a balance. In our example, only the one you have generated. Select this one, indicating that the payment will be paying that invoice (note the amount field getting populated). The credit card information is also pre-filled by the system with the customer's credit card on record. In this example, you want the 'Process real-time' check box set, so the payment is sent to the payment processor for immediate approval.

Clicking on 'Submit' takes you to a review page, where you have a chance to make sure that all the data is correct before it is applied. A click on the 'Submit' link of the review page finishes the process.

What is next?

Now you have a new customer, with an order that has invoiced the first month. This first invoice has been paid. From now on, the order will generate one invoice per month, starting a month from the day the order was created. These invoices will be automatically paid with the customer's credit card.

There is really nothing else to spend time on. Depending on your configuration settings jBilling will take care of notifying the customer that there is a new invoice, that a payment has been processed (and the outcome of it, success or failure), retrying failed payments, reminding the customer that a payment is required or that the credit card on record has expired, etc.

Well done! You have completed the basic Getting Started guide. It is the starting point to get yourself familiar with jBilling, your next stop is the 'Getting Started – BRMS' guide. It covers the usage of rules for rating, complex pricing and item relationship management through a Business Rules Management System (BRMS).

Latest News Items