Invoices

Kimai allows creating invoices from timesheet data in several formats.

Invoice number format

You can mix arbitrary characters and the allowed replacer from the list below. All examples represent the date 2019-07-09 (2019, July 9th):

• {date} - shortcut for ymd. Example: 190709 (default format before Kimai 1.9)
• {cname} - the customer name
• {cnumber} - the customer number
• {c} - counter for invoices of all times, starting at 1
• {cy} - counter for invoices this year, starting at 1
• {cm} - counter for invoices this month, starting at 1
• {cd} - counter for invoices this day, starting at 1
• {Y} - full numeric representation of a year (4 digits). Example: 2019
• {y} - two digit representation of a year. Example: 19
• {M} - numeric representation of a month, with leading zeros. Example: 07
• {m} - numeric representation of a month, without leading zeros. Example: 7
• {D} - day of the month, 2 digits with leading zeros. Example: 09
• {d} - day of the month without leading zeros. Example: 9
• {YY} - full numeric representation of a year (4 digits), to be used with decrement/increment (default increment = 1). Example: 2020
• {MM} - numeric representation of a month, to be used with decrement/increment (default increment = 1). Example: 10
• {DD} - day of the month, to be used with decrement/increment (default increment = 1). Example: 24
• {cc} - per customer invoice counter for all times, starting at 1
• {ccy} - per customer invoice counter for this year, starting at 1
• {ccm} - per customer invoice counter for this month, starting at 1
• {ccd} - per customer invoice counter for this day, starting at 1
• {cu} - per user (the one creating the invoice) invoice counter for all times, starting at 1
• {cuy} - per user (the one creating the invoice) invoice counter for this year, starting at 1
• {cum} - per user (the one creating the invoice) invoice counter for this month, starting at 1
• {cud} - per user (the one creating the invoice) invoice counter for this day, starting at 1
• {ustaff} - the user (the one creating the invoice) staff number, empty if not configured
• {uid} - the internal user (the one creating the invoice) ID

Each replacer (x) can be combined with a length formatter, which will prepend (X) leading zeros, eg. {x,X}. Example: to get a three digit long string with year counter use {cy,3}, which results in 001 for the first invoice of the year.

Incrementing the invoice counter

It is possible to increment the counter by adding a number to the result. For evaluated counters, Kimai takes the amount of found invoices and adds 1, but you can replace +1 with an addition like +3. This works for the following replacer: {c} and {cy} and {cm} and {cd} and {cc} and {ccy} and {ccm} and {ccd}.

Simply use the plus (+) after the replacer, eg. {cy+72}. This also works in combination with the length formatter, eg.: {cy+72,3}

Decrementing the invoice counter

You can decrement the counter subtracting a number from the result. For evaluated counters, Kimai takes the amount of found invoices and adds +1, but you can replace +1 with a subtraction like -12. This works for the following replacer: {c} and {cy} and {cm} and {cd} and {cc} and {ccy} and {ccm} and {ccd}.

Simply use the minus (-) after the replacer, eg. {cy-72}. This also works in combination with the length formatter, eg.: {cy-72,3}

Examples

Assume you already wrote 72 invoices this year (before you started to use Kimai), and your counter is an incrementing number per year, which is prefixed with the four digit year:

• {Y}/{cy+73,3} would result in 2020/073 for your first invoice

Assume that you want to change your invoice numbering and reset it to zero, you already wrote 72 invoices this year, and your counter is an incrementing number per year that should be prefixed with the four digit year:

• {Y}/{cy-72,3} would result in 2020/001 for your first invoice

Invoice state

Invoices can have multiple states:

• New - the invoice was just created
• Waiting for payment - the invoice was sent to the customer
• Invoice paid - the invoice was paid (you have to choose a payment date)
• Canceled - the invoice was accidentally created

Deleting invoices

Invoices should not be deleted, because this can cause all kinds of weird problems in Kimai (depending on your invoice number format).

You should instead “cancel” invalid invoices. Many users fear legal issues if they don’t have consecutive invoice numbers, please clarify that with your accountant - this is often not a legal requirement. Instead it is a completely regular workflow, that invoices get canceled (the used invoice number will not be released).

If you insist on deleting invoices, do NOT delete them if you already created invoices afterwards. This will cause troubles with your invoice counter, as Kimai is calculating invoice numbers from the amount of entries in the database. By deleting invoices you lower the amount of invoices in the database, and the next invoice number might be one that you already used.

Invoice deletion is disabled by default, because of all known problems with deletion. You can activate it enabling the permissions called delete_invoice.

Export state

Invoices and exports share the export state, which is used to mark timesheet records as processed. These records cannot be edited any longer by regular users and are excluded by default from further invoices and exports.

You need to tick the “mark as export” checkbox before saving the invoice, to automatically set the export state on all filtered timesheet records.

The “mark as export” checkbox is only available for users with the edit_export_other_timesheet permission.

For further information read the timesheet documentation.

Billable items only

Only billable items will be included in invoices.

By default, every timesheet records is billable, but users can set the billable flag on individual timesheets.

Expense items have a configurable billable flag per item and only the ones marked as billable (refundable) will be included.

Invoice document

The invoice system currently supports the following formats:

• PDF
  • through the use of Twig templates
  • filename must end with .pdf.twig
  • Pro: no need for additional software
  • Contra: you have to understand HTML, Twig and the MPDF library
  • the recommended invoice document format
• HTML
  • through the use of Twig templates
  • filename must end with .html.twig
  • Pro: no need for additional software, print or convert to PDF from your browser (if supported)
  • Contra: you have to understand HTML and Twig
• DOCX
  • OOXML - Open Office XML Text
  • Microsoft Word 2007-2013 XML
  • filename must end with .docx
  • Pro: simple customization and possibility to edit the invoice later on
  • Contra: Non-free software required
• ODS
  • Open Document Spreadsheet or OASIS, is the OpenOffice.org XML file format for spreadsheets supported by OpenOffice, LibreOffice, StarCalc, Microsoft and others
  • file extension: filename must end with .ods
  • Pro: open format, good for exporting and creating enhanced reports with an office software package
  • Contra: not ideal format for invoices (harder to customize)
• XLSX
  • Microsoft Excel™ 2007 shipped with a new file format, namely Microsoft Office Open XML SpreadsheetML, and Excel 2010 extended this still further with new features.
  • file extension: filename must end with .xlsx
  • Pro: good for creating enhanced reports with an office software package
  • Contra: Non-free software required, not ideal format for invoices

Create your own invoice document

Invoice documents are searched in two locations:

• var/invoices/ - does not exist by default, please create it when you add a new document
• 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
• You can configure different search directories through the config key kimai.invoice.documents if you want to add additional template source directories

After you changed an invoice template, you have to clear the cache to see the results.

More invoice templates

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

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

Twig templates

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.

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 loose 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 %}

PDF templates

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

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 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!

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

This row will then 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

Timesheet entry variables

For each timesheet record you can use these variables:

Customer variables

Variables for the customer who is receiving the invoice:

Project variables

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 variables

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 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.

Filter and search in the invoice archive

The search supports filtering by the fields:

• creation date
• customer
• state

Besides these filters, you can query for a free search term, which will be searched in the fields:

• comment
• customer name
• customer company

Additionally, you can filter for custom fields by using a search phrase like location:homeoffice. This would find all entries with the custom field location matching the term homeoffice.

The search terms will be found within the full value, so searching for office would find:

• I love working in my office
• Office
• This office is beautiful
• Our offices are very noisy

Attention: checkboxes have the values 0 (not checked) and 1 (checked).

You can mix the search term and use multiple meta-field queries:

• location:homeoffice hello - find all entries matching the search term hello with the custom field location matching the term homeoffice
• location:homeoffice contract:fulltime - find all entries with the custom field combination: location matching homeoffice and contract matching fulltime
• expired:0 finds all items whose expired checkbox is off

There are also special operators, which can be used in conjunction with custom fields (since Kimai 1.19.1):

• The   empty string (e.g. location:) will find all entries whose value in the location field is either empty or not existing
• The ~ search term (e.g. location:~) will find all entries that are missing the custom field (created before the field was created)
• The * search term (e.g. location:*) will find all entries that have any value in the location field (basically the opposite of ~)