Invoice templates

Creating custom invoice templates for

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

Do NOT change the default templates, but copy the file and save it at var/invoices/

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:

entries which is an array of arrays, with the first level representing the invoice items and the second level being Timesheet entry variables (see below)
invoice which is an array of variables (see Template variables below), just with a different syntax for access, e.g.: {{ invoice['invoice.due_date'] }} instead of ${invoice.due_date}
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.

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>

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, multiple twig functions and filters are disabled in the invoice renderer. Therefor you cannot for example 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

Key	Description
${invoice.due_date}	The due date for the invoice payment formatted in the requested locale
${invoice.due_date_process}	The due date for the invoice payment, to be formatted with the twig filter `date()`
${invoice.date}	The creation date of this invoice
${invoice.date_process}	The creation date of this invoice, to be formatted with the twig filter `date()`
${invoice.number}	The generated invoice number
${invoice.currency}	The invoice currency
${invoice.currency_symbol}	The invoice currency as symbol (if available)
${invoice.total_time}	The total working time (entries with a fixed rate are always calculated with 1)
${invoice.duration_decimal}	The total working time as decimal value
${invoice.language}	The invoices language as two character code
${invoice.total}	The invoices total (including tax) with currency
${invoice.total_nc}	The invoices total (including tax) without currency
${invoice.total_plain}	The invoices total (including tax) as unformatted value
${invoice.subtotal}	The invoices subtotal (excluding tax) with currency
${invoice.subtotal_nc}	The invoices subtotal (excluding tax) without currency
${invoice.subtotal_plain}	The invoices subtotal (excluding tax) as unformatted value
${invoice.currency}	The invoices currency as string (like EUR or USD)
${invoice.vat}	The VAT in percent for this invoice
${invoice.tax}	The tax of the invoice amount with currency
${invoice.tax_nc}	The tax of the invoice amount without currency
${invoice.tax_plain}	The tax of the invoice amount as unformatted value
${invoice.tax_hide}	A boolean flag indicating if the tax field should be hidden (only applies if tax = 0)
${template.name}	The invoice name, as configured in your template
${template.company}	The company name, as configured in your template
${template.address}	The invoicing address, as configured in your template
${template.title}	The invoice title, as configured in your template
${template.payment_terms}	Your payment terms, might be multiple lines
${template.due_days}	The amount of days for the payment, starting with the day of creating the invoice
${template.vat_id}	The Vat ID for this invoice
${template.contact}	Extended contact information, might be multiple lines
${template.payment_details}	Extended payment details like bank accounts, might be multiple lines
${query.begin}	The query begin as formatted short date
${query.begin_process}	The query begin, to be formatted with the twig filter `date()`
${query.end}	The query end as formatted short date
${query.end_process}	The query end, to be formatted with the twig filter `date()`
${query.month}	The month for this query (begin date) DEPRECATED
${query.month_number}	The numerical value for the month (with leading zero) DEPRECATED
${query.day}	The day for the queries begin as numerical value with leading zero DEPRECATED
${query.year}	The year for this query (begin date) DEPRECATED
${query.begin_month}	The month for the queries begin date
${query.begin_month_number}	The numerical value for the month of the queries begin date with leading zero
${query.begin_day}	The day for the queries begin as numerical value with leading zero
${query.begin_year}	The year for the queries begin date
${query.end_month}	The month for the queries end date
${query.end_month_number}	The numerical value for the month of the queries end date with leading zero
${query.end_day}	The day for the queries end as numerical value with leading zero
${query.end_year}	The year for the queries end date
${query.activity.name}	Activity name (only if exactly one activity was filtered)
${query.activity.comment}	Activity comment/description (only if exactly one activity was filtered)
${query.project.name}	Project name (only if exactly one project was filtered)
${query.project.comment}	Project comment/description (only if exactly one project was filtered)
${query.project.order_number}	Project Order-Number (only if exactly one project was filtered)
${user.display}	The current users display name
${user.email}	The current users email
${user.name}	The current users name
${user.alias}	The current users alias
${user.title}	The current users title
${user.see_others}	A boolean indicating if the current user can see other users items
${user.meta.X}	The current users preference named `X`

Timesheet entry variables

For each timesheet record you can use these variables:

Key	Description	Example
${entry.row}	An empty string, used as template row for docx
${entry.description}	The entries description	foo bar
${entry.description_safe}	The entries description. If that is empty the activity name will be used.	foo bar
${entry.amount}	DEPRECATED (do not use): The decimal duration for this entry. If this is a fixed rate entry, it contains the formatted amount.	2.78
${entry.rate}	The rate for one unit of the entry (normally one hour) with currency	1.100,01 EUR
${entry.rate_nc}	The rate for one unit of the entry without currency	1100,01
${entry.rate_plain}	The rate for one unit of the entry as unformatted value	1100.01
${entry.total}	The total rate for this entry with currency	1.278,33 EUR
${entry.total_nc}	The total rate for this entry without currency	1.278,33
${entry.total_plain}	The total rate as unformatted value	1278.33
${entry.currency}	The currency for this record as string (like EUR or USD)	EUR
${entry.duration}	The duration in seconds	10020
${entry.duration_format}	The duration in human-readable format	02:47
${entry.duration_decimal}	The duration in decimal format (with localized separator)	2.78
${entry.duration_minutes}	The duration in minutes with no decimals	167
${entry.begin}	The begin date (format depends on the users language)	27.10.2018
${entry.begin_time}	The formatted time for the begin of this entry	14:57
${entry.begin_timestamp}	The timestamp for the begin of this entry	1542016273
${entry.end}	The begin date (format depends on the users language)	27.10.2018
${entry.end_time}	The formatted time for the end of this entry	17:44
${entry.end_timestamp}	The timestamp for the end of this entry	1542016273
${entry.date}	The start date when this record was created	27.10.2018
${entry.date_process}	The start date of this record, to be formatted with the twig filter `date()`
${entry.week}	The start week number when this record was created	39
${entry.weekyear}	The corresponding year to the week number	2018
${entry.user_id}	The user ID	1
${entry.user_name}	The username	susan_super
${entry.user_alias}	The user alias	Susan Miller
${entry.user_preference.foo}	The user preference called `foo`	bar
${entry.activity}	Activity name	Post production
${entry.activity_id}	Activity ID	124
${entry.project}	Project name	Nemesis
${entry.project_id}	Project ID	10
${entry.customer}	Customer name	Acme Studios
${entry.customer_id}	Customer ID	3
${entry.meta.foo}	The meta field with the internal name `foo` (must be in lowercase letters, e.g. `FOO` will be available as `${entry.meta.foo}`. Only available if the field is visible.
${entry.tags}	Comma separated list of all tags	foo, bar
${entry.type}	The type of this entry (plugins can add custom types)	timesheet
${entry.category}	The category of this entry (plugins can add custom types)	work

Customer variables

Variables for the customer who is receiving the invoice:

Key	Description (highlighted words are the names in the UI)
${customer.id}	The internal customer ID (do not display that on your invoices)
${customer.name}	The customer `name`
${customer.comment}	The `description` of this customer
${customer.address}	The customer `address`
${customer.contact}	Usually the name of the customer `contact` person
${customer.company}	The `company name`
${customer.vat}	The customer `Vat ID`
${customer.number}	The customer `account` number
${customer.country}	The `country` of the customer location
${customer.homepage}	A URL to the customer `homepage`
${customer.phone}	The customers `phone` number
${customer.mobile}	The customers `mobile` number
${customer.email}	The customers `email` address
${customer.fax}	The customers `fax` number
${customer.meta.foo}	The customer meta field with the internal name `foo` (must be in lowercase letters, e.g. `FOO` will be available as `${customer.meta.foo}`. Only available if the field is visible.
${customer.budget_open}	The open monetary budget for this customer at the end date of your filter query (formatted with currency)
${customer.budget_open_plain}	The open monetary budget for this customer at the end date of your filter query (plain float value)
${customer.time_budget_open}	The open time budget for this customer at the end date of your filter query (formatted)
${customer.time_budget_open_plain}	The open time budget for this customer at the end date of your filter query (integer value = seconds)
${customer.invoice_text}	The configurable invoice text for that customer

Project variables

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

Key	Description (highlighted words are the names in the UI)
${project.id}	The internal project ID (do not display that on your invoices)
${project.name}	The project `name`
${project.comment}	The `description` of this project
${project.order_number}	The project `order number`
${project.start_date}	The `Project start` date-time
${project.end_date}	The `Project end` date-time
${project.order_date}	Projects `order date`-time
${project.budget_money}	Projects budget including currency
${project.budget_money_nc}	The projects budget without currency
${project.budget_money_plain}	The projects budget as unformatted value
${project.budget_time}	The projects time-budget as seconds
${project.budget_time_decimal}	The projects time-budget in decimal format (with localized separator)
${project.budget_time_minutes}	The projects time-budget in minutes with no decimals
${project.number}	The project number
${project.invoice_text}	The project invoice-text
${project.meta.foo}	The project meta field with the internal name `foo` (must be in lowercase letters, e.g. `FOO` will be available as `${project.meta.foo}`. Only available if the field is visible.
${project.budget_open}	The open monetary budget for this project at the end date of your filter query (formatted with currency)
${project.budget_open_plain}	The open monetary budget for this project at the end date of your filter query (plain float value)
${project.time_budget_open}	The open time budget for this project at the end date of your filter query (formatted)
${project.time_budget_open_plain}	The open time budget for this project at the end date of your filter query (integer value = seconds)

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 variables

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

Key	Description (highlighted words are the names in the UI)
${activity.id}	The internal activity ID (do not display that on your invoices)
${activity.name}	The activity `name`
${activity.comment}	The `description` of this activity
${activity.number}	The activity number
${activity.invoice_text}	The activity invoice-text
${activity.meta.foo}	The activity meta field with the internal name `foo` (must be in lowercase letters, e.g. `FOO` will be available as `${activity.meta.foo}`. Only available if the field is visible.
${activity.budget_open}	The open monetary budget for this activity at the end date of your filter query (formatted with currency)
${activity.budget_open_plain}	The open monetary budget for this activity at the end date of your filter query (plain float value)
${activity.time_budget_open}	The open time budget for this activity at the end date of your filter query (formatted)
${activity.time_budget_open_plain}	The open time budget for this activity at the end date of your filter query (integer value = seconds)

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 documents

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.

Invoices – Create invoices within Kimai in several file formats
Invoice – Enhanced invoice features