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:

invoice html

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:

  1. Upload the invoice template

  2. Upload the translation for all the supported locales

  3. Upload the catalog translation for all the locales (if required)

Let us look at each step in detail.

  1. Upload the invoice template:

    1. 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>
    2. 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
    3. Alternatively, you can upload this file via Kaui by going to your admin tenant page (InvoiceTemplate) tab:

      custom invoice template

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

    1. 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
    2. 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
    3. Alternatively, you can upload this file via Kaui by going to your admin tenant page (InvoiceTranslation) tab:

      invoice html config

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

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

    1. Create a catalog translation for locale fr_FR as follows:

      gold-monthly = plan Or mensuel
    2. 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
    3. Alternatively, you can upload this file via Kaui by going to your admin tenant page (CatalogTranslation) tab:

      catalog translation

  4. Generate an HTML invoice.

    1. 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"
    2. Alternatively, you can generate the HTML invoice via Invoices tab in Kaui:

    view html invoice