Invoice Templates

Kill Bill invoices can be rendered as HTML using our render HTML invoice API. This can be useful, for instance, to show the invoices directly to your customer on the billing section of your website. This document explains how to configure custom invoice templates.

Invoice Template Configuration Overview

Kill Bill uses the mustache engine for generating HTML invoices.

There are two main components while generating an HTML invoice:

A template: This constitutes the body of the template. It includes static text as well as variables which are replaced at runtime by the mustache engine.
A resource bundle: This includes one or more files that specify translations corresponding to a locale. You can read the Kill Bill Internationalization document to know more about resource bundles.

Defaults

Kill Bill provides a default invoice template which looks like this:

However, users can upload their own custom templates.

In addition, Kill Bill also provides a default resource file. This file contains translation strings corresponding to the default template and the en_US locale. Users can also upload their own resource files.

Customizing Invoice Template

This section explains how you can upload your own invoice template/translation resource bundle.

At a high-level, you need to execute the steps given below:

Upload the invoice template
Upload the translation for all the supported locales
Upload the catalog translation for all the locales (if required)

Let us look at each step in detail.

Upload the invoice template:

Create a file $SOME_PATH_PREFIX/HtmlInvoiceTemplate.mustache as follows:

<html>
    <head>
        <style type="text/css">
            th {align=left; width=225px; border-bottom: solid 2px black;}
        </style>
    </head>
    <body>
        <h1>{{text.invoiceTitle}}</h1>
        <table>
            <tr>
                <td rowspan=3 width=350px>Insert image here</td>
                <td width=100px/>
                <td width=225px/>
                <td width=225px/>
            </tr>
            <tr>
                <td />
                <td align=right>{{text.invoiceDate}}</td>
                <td>{{invoice.formattedInvoiceDate}}</td>
            </tr>
            <tr>
                <td />
                <td align=right>{{text.invoiceNumber}}</td>
                <td>{{invoice.invoiceNumber}}</td>
            </tr>
            <tr>
                <td>{{text.companyName}}</td>
                <td></td>
                <td align=right>{{text.accountOwnerName}}</td>
                <td>{{account.name}}</td>
            </tr>
            <tr>
                <td>{{text.companyAddress}}</td>
                <td />
                <td />
                <td>{{account.email}}</td>
            </tr>
            <tr>
                <td>{{text.companyCityProvincePostalCode}}</td>
                <td />
                <td />
                <td>{{account.phone}}</td>
            </tr>
            <tr>
                <td>{{text.companyCountry}}</td>
                <td />
                <td />
                <td />
            </tr>
            <tr>
                <td><{{text.companyUrl}}</td>
                <td />
                <td />
                <td />
            </tr>
        </table>
        <br />
        <br />
        <br />
        <table>
            <tr>
                <th>{{text.invoiceItemBundleName}}</td>
                <th>{{text.invoiceItemDescription}}</td>
                <th>{{text.invoiceItemServicePeriod}}</td>
                <th>{{text.invoiceItemAmount}}</td>
            </tr>
            {{#invoice.invoiceItems}}
            <tr>
                <td>{{description}}</td>
                <td>{{planName}}</td>
                <td>{{formattedStartDate}}{{#formattedEndDate}} - {{formattedEndDate}}{{/formattedEndDate}}</td>
                <td>{{invoice.currency}} {{amount}}</td>
            </tr>
            {{/invoice.invoiceItems}}
            <tr>
                <td colspan=4 />
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>{{text.invoiceAmount}}</strong></td>
                <td align=right><strong>{{invoice.chargedAmount}}</strong></td>
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>{{text.invoiceAmountPaid}}</strong></td>
                <td align=right><strong>{{invoice.paidAmount}}</strong></td>
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>{{text.invoiceBalance}}</strong></td>
                <td align=right><strong>{{invoice.balance}}</strong></td>
            </tr>
        </table>
    </body>
</html>

Upload the file via the following cURL command:

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H 'X-Killbill-CreatedBy: admin' \
     -H "Content-Type: text/html" \
     -X POST \
     --data-binary @$SOME_PATH_PREFIX/HtmlInvoiceTemplate.mustache \
     http://127.0.0.1:8080/1.0/kb/invoices/template

Alternatively, you can upload this file via Kaui by going to your admin tenant page (InvoiceTemplate) tab:

Upload the invoice translation for the desired locale. For instance, in order to upload the translation for the locale fr_FR:

Create a file $SOME_PATH_PREFIX/InvoiceTranslation_fr_FR.properties as follows:

invoiceEmailSubject=Nouvelle Facture
invoiceTitle=FACTURE
invoiceDate=Date:
invoiceNumber=Facture #
invoiceAmount=Montant à payer
invoiceAmountPaid=Montant payé
invoiceBalance=Nouveau montant

accountOwnerName=Chauffeur

companyName=Killbill, Inc.
companyAddress=P.O. Box 1234
companyCityProvincePostalCode=Springfield
companyCountry=USA
companyUrl=http://kill-bill.org

invoiceItemBundleName=Armes
invoiceItemDescription=Description
invoiceItemServicePeriod=Période de facturation
invoiceItemAmount=Montant

processedPaymentCurrency=(*) Le payment à été payé en
processedPaymentRate=Le taux de conversion est

Upload the file via the following cURL command:

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H 'X-Killbill-CreatedBy: admin' \
     -H "Content-Type: text/plain" \
     -X POST \
     --data-binary @$SOME_PATH_PREFIX/InvoiceTranslation_fr_FR.properties \
     http://127.0.0.1:8080/1.0/kb/invoices/translation/fr_FR

Alternatively, you can upload this file via Kaui by going to your admin tenant page (InvoiceTranslation) tab:

Additional resource files can be uploaded for different locales as required.

In addition to the invoice template translation, you can also upload a catalog translation file.

Create a catalog translation for locale fr_FR as follows:
```
gold-monthly = plan Or mensuel
```

Upload the file via the following cURL command:

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H 'X-Killbill-CreatedBy: admin' \
     -H "Content-Type: text/plain" \
     -X POST \
     --data-binary @$SOME_PATH_PREFIX/CatalogTranslation_fr_FR.properties \
     http://127.0.0.1:8080/1.0/kb/invoices/catalogTranslation/fr_FR

Alternatively, you can upload this file via Kaui by going to your admin tenant page (CatalogTranslation) tab:

Generate an HTML invoice.

Execute the following cURL command:

curl -v \
     -u admin:password \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H "Content-Type: application/json" \
     -H 'X-Killbill-CreatedBy: admin' \
     "http://127.0.0.1:8080/1.0/kb/invoices/1785b3d5-24b3-4d17-94ce-310aeb74bc63/html"

Alternatively, you can generate the HTML invoice via Invoices tab in Kaui:

Customizing Invoice Data

Sometimes, you may need to customize the data in the invoice (add additional fields, custom logic for existing fields, etc.). For this, you will need to create a custom invoice formatter plugin. We have a sample plugin here.

Further Information

PreviousPrev NextNext