Customers in Kimai
Customers in Kimai are used to manage project and activities, which are then used for time-records.
It is best-practice to have a customer for your own company, to track times for administrative and other internal work.
Creating a customer
Default values for new customers can be configured at System > Settings.
Each customer can be assigned its own color, for easier identification in timesheet listing.
If a project or an activity linked to the customer does not have its own color, the customers color will be used.
The default color code is
The customer currency is used when displaying the recorded entries in the timesheet.
It is also used for printing invoices, which is the reason while the invoice screen needs one applied customer filter before any data will be shown.
Billable configuration of a Customer defines whether new timesheet (in
Automatic mode) will be billable.
Please read the billable documentation to understand the
Budgets help you to watch your progress and to stay within contract boundaries.
If the System > Settings configuration
Allow overbooking of stored budgets is not active,
Kimai will prevent that records will be created, which would go beyond your configured budgets.
Currently, the visibility of budgets cannot be limited independently. So if you want to show progress to your users, you cannot show only the time budget (this will be changed in the future).
budget_customer are used
to check if the logged-in user can see the budgets.
Kimai knows two budget types. The default budget type is
lifetime (which is used if the
budget type is empty),
the other available budget type is
Lifetime budget- uses all records of all times to calculate progress and budget usage
Monthly budget- uses all records of the selected month to calculate progress and budget usage
No matter which budget type is used, it does not influence invoice amounts. There is no automatism that will add a monthly budget to your invoice (you have to create expenses or time records for that).
Monthly budgets are used for every month, no matter how many days are recorded. Kimai does not take range limits into account to calculate partial budgets (e.g. project start/end or the first record created for a customer).
Money budgets will be used to calculate reports.
For Kimai there is no difference between money and time budgets. If there are multiple people with a different hourly rate working on the same tasks, then money and time budget will differ in their outcome.
Only billable records will be used to calculate the remaining budget.
The time budget should be entered in the format
hh:mm or decimal
Time budgets will be used to calculate reports.
If you are using money budget and want to show progress to your users, it is a good idea to calculate the hourly rate by using
money budget / average hourly rate.
Only billable records will be used to calculate the remaining budget.
You can configure prices on different levels in Kimai. It starts from the user hourly prices and goes from Customers to Projects and Activities. Please read the price documentation to find out more how rates are calculated.
On the detail page of the selected item (which you find by clicking a row in the listing table or select
Show from the dropdown menu)
you find the
Hourly price section. By default, you see the message
No prices have been configured.
You configure new price rules by clicking the
+ button in the upper-right of the
A user needs the two permissions to be able to see and edit prices:
- one of:
- one of:
Edit price screen
edit price screen has four settings:
User- the user this price applies to - if no user is chosen it applies to everyone without explicit personal rule
Price- the price to be charged (per hour)
Internal price- the internal price (or “costs” if you will) to apply (per hour); if this is not specified, the normal price is used for calculation.
Fixed price- if this is ticked, each time record gets the configured
Pricevalue applied, regardless of the record duration
If no user was chosen, this rule applies to every user, except those who have a explicit
User specific price configured.
User specific price
Every rule the defines a user is a
user specific price and those always win over
Catch-all price configurations.
The following example contains two price rules:
The first one is a
Catch-all price that applies to everyone who is recording times for this customer.
So every hour counts with 50 € towards the budget of this customer and has internal costs of 25 €.
Every recorded hour has a gross margin of 25 € / hour.
The second rule applies to the user
DY who (as only user) has a
User specific price for this customer.
Even though she has a higher internal cost of 45 € / hour, her work earns 85 € / hour, which leads to a gross margin of 40 € / hour.
By toggling the visibility on a customer, you:
- hide the customer from all drop-downs
- hide the customer from the default list in the customer administration
- hide all projects for this customer from all drop-downs, regardless of their visibility state
- hide all projects for this customer from the default list in the projects administration
- hide the activities for all customer projects from all drop-downs, regardless of their visibility state
- hide the activities for all customer projects from the default list in the activities administration
- all currently linked objects will still show the customer in the dropdown as pre-selected option
- you can still change the customer on timesheet records and projects, which used it before
- you cannot create new projects for this customer
- you cannot create new timesheet records for this customer
- you can still access the hidden entries by changing the visibility filter on the toolbars
The visibility filter in the toolbar has three state:
- Visible: Yes (all customers that are visible)
- Visible: No (all customers that are invisible)
- Visible “empty” (all customers, not filtering on their visibility)
Filter and search
The search supports filtering by the fields:
Besides these filters, you can query for a free search term, which will be searched in the fields:
Additionally, you can filter for custom fields by using a search phrase like
This would find all entries with the custom field
location matching the term
The search terms will be found within the full value, so searching for
office would find:
I love working in my office
This office is beautiful
Our offices are very noisy
Attention: checkboxes have the values
0 (not checked) and
You can mix the search term and use multiple meta-field queries:
location:homeoffice hello- find all entries matching the search term
hellowith the custom field
locationmatching the term
location:homeoffice contract:fulltime- find all entries with the custom field combination:
expired:0finds all items whose
There are also special operators, which can be used in conjunction with custom fields (since Kimai 1.19.1):
location:) will find all entries whose value in the
locationfield is either empty or not existing
~search term (e.g.
location:~) will find all entries that are missing the custom field (created before the field was created)
*search term (e.g.
location:*) will find all entries that have any value in the
locationfield (basically the opposite of
Deleting a customer
Customers can be deleted from the Customer listing view via
Administration > Customers.
Usually it is not a good idea to delete a used customer, consider to switch the visibility instead to hide it.
Right-click on a row (or open the action dropdown at the end of it) to see all available actions for the selected customer.
The last action in the list is
Delete - once you click it you wil get a feedback screen which either tells you that the
customer is unused and can be safely deleted, or it will show you quick stats of the customer and then ask you to re-assign
the attached timesheets to another customer.