User manual
User manual Developer Self-hosted
Keep track of your expenses and include them in your invoices

Expenses

Table of contents

  • Record all your expenses and show them in a table view
    • The data can be searched- and filtered (see screenshots)
  • All (billable) expenses will be automatically included in your invoices
    • Negative amounts allow for complex bookings, budget and invoice adjustments
  • Manage expenses via API
  • Export expenses in: Excel, PDF, HTML
  • Support for custom-fields (see Custom-fields plugin)
  • Include expenses in Kimai export module
  • Import expenses from Kimai 1

Expenses will be assigned to free configurable categories and each category has:

  • name
  • visibility flag
  • default cost
  • color
  • help text (will be shown when creating an expense)
  • description (will be copied into the expense description upon selection)

Each expense has the following fields:

  • a date-time
  • category (see above)
  • user
  • project (and customer)
  • activity (optional)
  • description (free text field)
  • the cost (can be hidden for default user, if you use default cost via category)
  • an amount (see it as multiplier, use 1 if you want to charge the cost only)
  • a billable flag (non-billable expenses will not be added to your invoices)
  • an export flag (to make sure, that each expense will be invoiced only once)

Usage

When logged in as user with sufficient permissions, you will see the expense administration screen at /en/expenses/.

During the installation a Demo category will be created, so you can immediately start adding expenses. You can rename it after your first test.

Invoices

As expenses will be automatically included in your invoices, you might want to distinguish between expenses and timesheets.

Since Kimai 1.6.2 and ExpensesBundle 1.5 this can be done with the invoice template variable ${entry.type}. The value will be expense and can be used for example in Excel with ifthan formulas or in combination with a conditional format.

The invoice template variable ${entry.category} will contain the category name of the expense.

The search supports filtering by the fields:

  • daterange
  • customer
  • project
  • activity
  • expense category
  • user
  • billable
  • exported

The free search term will query the field:

  • description

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 ~)

Permissions

Permission Name Description
view_expense allows access to the expenses screen
edit_expense edit existing expenses
edit_expense_cost edit the cost of a single expense (deactivate this, if you want to provide default costs via the category)
export_expense export expenses
create_expense create new expenses
delete_expense delete existing expenses
manage_expense_category manage expense types
edit_exported_expense allow to edit and delete exported expenses

Pre-defined permissions are assigned to all default user roles.

The following restrictions are in place for accessing other user’s data:

  • can only be seen by users who own the view_other_timesheet
  • users that own the view_expense permission but NOT view_other_timesheet will only see own expenses
  • the visible data for non-admin users (permission view_all_data) is limited by team assignments