Invoice templates

The invoice system currently supports the following file formats for generating invoices:

PDF

• Filename must end with .pdf.twig
• Pro: no need for additional software
• Contra: you have to understand HTML and Twig
• The recommended invoice document format

HTML

• Filename must end with .html.twig
• Pro: no need for additional software, print or convert to PDF from your browser
• Contra: you have to understand HTML and Twig

DOCX

• Microsoft Word
• Filename must end with .docx
• Pro: possibility to edit the invoice later on, can be converted to PDF
• Contra: not accepted for invoices in many countries, non-free software required

ODS

• Open Document Spreadsheet is supported by OpenOffice, LibreOffice, StarCalc, Microsoft and others
• File extension: filename must end with .ods
• Pro: free and open format, can be converted to PDF
• Contra: not accepted for invoices in many countries

XLSX

• File extension: filename must end with .xlsx
• Pro: good for creating enhanced reports with an office software package
• Contra: not accepted for invoices in many countries, non-free software required

Create a template

Invoice documents are searched in two locations:

• var/invoices/ - does not exist by default, please create it when you add your templates
• templates/invoice/renderer/ - don’t change files in here, will be overwritten with the next update

Be aware of the following rules:

• Documents are addressed by their filename without extension (e.g. kimai.html.twig results in kimai)
• You can use every document name only once: so having kimai.html.twig and kimai.docx will lead to unpredictable results (the first file to be found takes precedence)
• Kimai looks for templates in var/invoices/ first, so you can overwrite default templates
• You should store your templates in var/invoices/, as this directory is not shipped with Kimai and not touched during updates

Pre-made templates

There is a place where the community can share invoice templates. Please do so, if you created a nice looking and re-usable template yourself!

The repository for all templates is https://github.com/kimai/invoice-templates and it includes installation notes.

PDF templates

PDF files are generated from HTML, which itself is created with a Twig template (see below).

There is so much to say about PDF templates, that there is a dedicated page about PDF templates.

Twig templates (HTML)

Twig templates are used to generate HTML and PDF files.

Generally speaking, you have two main variables in your template which you should use:

• invoice which is an array of variables (see Global variables below)
• entries which is an array of arrays, representing the invoice items and their Invoice items

Attention: accessing the model variable (instance of App\Model\InvoiceModel) directly is deprecated and will be removed in the future (no BC promise given!)

Please see the default templates at GitHub to find out which variables can be used.

Want to include an image in your template? Use the asset tag for referencing relative URLs (this example points to the directory public/images/my-logo.png):

<img src="{{ asset('images/my-logo.png') }}">

But the safest way is to host your images on your own domain:

<img src="https://www.example.com/images/my-logo.png">

Due to security reasons, most twig functions and filters are disabled in the invoice renderer. Therefor you cannot use include or embed to include other templates.

After you changed a twig template, you have to clear the cache to see the results.

Custom fields

Iterating above all entries (line items) in the invoice with {% for line in entries %} allows access to your custom fields.

Want to use a timesheet custom-field in your template?

{% if line['entry.meta.foo'] is defined %}
    Foo: {{ line['entry.meta.foo'] }}
{% endif %}

Please be aware:

• you can access timesheet custom fields only if you use the “sum calculation” standard, which creates one invoice line item per timesheet.
• if you group timesheets, e.g., by project, you lose access to their custom fields.
• entries could be of type “expense” or other types (depending on your used plugins), you can test that with {% if line['entry.type'] == 'timesheet' '%}

Want to use a customer custom-field in your template?

{% if invoice['customer.meta.foo'] is defined %}
    Foo: {{ invoice['customer.meta.foo'] }}
{% endif %}

Want to use a project custom-field in your template?

{% if line['entry.project.meta.foo'] is defined %}
    Foo: {{ line['entry.project.meta.foo'] }}
{% endif %}

Want to use a user preference in your template?

{% if line['entry.user_preference.foo'] is defined %}
    Foo: {{ line['entry.user_preference.foo'] }}
{% endif %}

Docx templates

Docx templates are processed by PHPWord and its TemplateProcessor.

Important: You have to add the variable ${entry.row} in the table row that will be duplicated for each entry, otherwise the records will not be rendered at all. In that case only the global values will be replaced!

The row containing this variable will be cloned for every included (timesheet) record.

The variable ${entry.row} will be removed during the rendering process, it will not show up in your generated invoices.

See below in Template variables to find out which variables you can use in your template.

Find out more about PHPWord templates here.

Spreadsheets (ODS and XLSX)

Spreadsheet templates are powered by PhpSpreadsheet.

Important: within the first 100 rows of the active spreadsheet you MUST-HAVE the template row for timesheet entries, which means there must be a value starting with ${entry. in one of the first 10 columns, otherwise no timesheet records will be rendered.

If you don’t have that, you will see the error Invalid invoice document, no template row found.. This error might also happen if you have multiple sheets in your spreadsheet, and save the file while the active sheet is one without the ${entry. placeholder.

Check the default templates if that doesn’t make sense to you ;-)

The row containing the ${entry. template will be cloned for every timesheet entry.

See below in Template variables to find out which variables you can use.

Template variables

Be aware, that the following list of variables is working for the “document” based formats (ODS, XLSX, DOCX).

Twig rendering is different, you have to access the variables with {{ invoice['xxx.yyy'] }} instead of ${xxx.yyy}.

Date variables have equivalents with the suffix _process, so you can use them in combination with the Twig filter for date formatting e.g. |date('d. m. Y.'). So you can either use the pre-formatted date value or you can convert it yourself. The example {{ invoice['invoice.due_date'] }} would then be converted to {{ invoice['invoice.due_date_process']|date('d. m. Y.') }}.

Global variables

Tax Rows

Tax rows are only available in Twig. You can loop all tax rows with {% for tax in invoice['invoice.tax_rows'] %}.

Invoice items (timesheets)

You can loop all invoice items in Twig with {% for item in entries %}. For all other formats see docs above.

Invoice issuer

The invoice issuer is the company sending the invoice.

Customer

The customer is the company receiving the invoice.

Project

The following variables exist, if projects could be found in the filtered data:

If more than one project was found, you will have further variables (same list as above) called ${project.1.name}, ${project.2.name} and so on. The order is not guaranteed, so it is not recommended relying on those variables. If your template relies on a {$project.X} variable, it is recommended to limit the invoice data with the project search filter.

Activity

The following variables exist, if activities could be found in the filtered data:

If more than one activity was found, you will have further variables (same list as above) called ${activity.1.name}, ${activity.2.name} and so on. The order is not guaranteed, so it is not recommended relying on those variables. If your template relies on a {activity.X} variable, it is recommended to limit the invoice data with the activity search filter.

Uploading invoice templates

You can upload invoice documents via the UI at /en/invoice/document_upload.

Due to security restrictions currently only the upload of the following formats is allowed: DOCX, ODS, XLSX.

There is a known bug in LibreOffice which exports DOCX files with a wrong mime-type. These files will not be accepted by Kimai with the error This file type is not allowed (read this issue for more information). The workaround is to change the document with another word processor: Apple pages, Google Drive and Microsoft 365 Online Office will export the DOCX files with the correct mimetype.

Twig debug template

Use this debug template to find out which variables are available:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>{{ invoice['invoice.number'] }}-{{ invoice['customer.company']|default(invoice['customer.name'])|u.snake }}</title>
    <style type="text/css">
        {{ encore_entry_css_source('invoice-pdf')|raw }}
    </style>
</head>
<body>
<div class="wrapper">
    <h3>The following list of variables is available for this invoice:</h3>
    <p>Please note, that the available variables will change depending on your search. E.g. the {{ '{{ project }}' }} variables are only available if you selected a project in your search filter.</p>
    <table class="items">
        <tr>
            <th>Variable</th>
            <th>Value</th>
        </tr>
        {% for name, value in invoice %}
            <tr class="{{ cycle(['odd', 'even'], loop.index0) }}">
                <td>{{ "{{ invoice['" ~ name ~ "'] }}" }}</td>
                <td>{{ invoice[name] }}</td>
            </tr>
        {% endfor %}
    </table>
    <h3>The following list is available for all timesheet entries, which can be rendered like this:</h3>
    <pre>
    {{ '{%' }} for entry in entries {{ '%}' }}
    &lt;ul&gt;
        {{ '{%' }} for name, value in entry {{ '%}' }}
            &lt;li&gt;{{ '{{ name }}' }}: {{ '{{ value }}' }}&lt;/li&gt;
        {{ '{%' }} endfor {{ '%}' }}
    &lt;/ul&gt;
    {{ '{%' }} endfor {{ '%}' }}
    </pre>
    <p>The table below contains only the first timesheet record:</p>
    <table class="items">
        <tr>
            <th>Variable</th>
            <th>Value</th>
        </tr>
        {% for entry in entries|slice(1) %}
            {% for name, value in entry %}
                <tr class="{{ cycle(['odd', 'even'], loop.index0) }}">
                    <td>{{ "{{ entry['" ~ name ~ "'] }}" }}</td>
                    <td>{{ value }}</td>
                </tr>
            {% endfor %}
        {% endfor %}
    </table>
</div>
</body>
</html>