Expenses

The Expenses module enables you to manage and track your organization's business related expenses, whether they are goods, or services. Expense records also support billing them to your clients, so you can pass along the costs directly through your invoices. Effective use of the expense module can help you track and monitor your organization's cash flow, and keep up with your taxes.

Expenses Module View

When you select the Expenses module from the navigation menu on the left hand side of the screen, you will be taken to the table view listing and sorting all available expense records.

From the table view you can sort expense records by the various status filters on top of the table. You can use the Filter text box to search for an expense number, vendor, or amount. A More Actions menu to the right of each entry in the table shows a list of available management actions you can take against an expense record, such as editing, cloning to a new expense record, cloning to a new recurring expense record, archiving, or deleting.

Viewing/Editing an Expense

Simply click on an expense number from the table to view/edit that expense.

The view/edit panel for an expense record has all the details about the record broken into four sections, as follows:

Details

• Status: the status of the expense - it's automatically set; see See Lifecycle of an Expense
• Expense Number: the expense number is best left alone, so it can be automatically generated by Invoice Ninja. The policies governing generated numbers can be found in Settings > Generated Numbers.
• Vendor: Link the expense to a vendor by selecting an available vendor record from the list here. (Vendor = who the expense is paid TO).
• Client: Link the expense to a client by selecting an available client record. When creating an invoice from an expense, the new invoice will also be automatically be assigned to this client.
• Project: select a project the expense is linked to
• Category: put the expense in an expense category - expense categories can also be managed from Settings > Expense Settings
• User: link an admin portal user to the expense. The User option can be used in the reports for tracking, but can also be used to give a specific user permission to view/edit an individual record.
• Tax: Expense Tax Rates must first be enabled under Settings > Tax Settings for this tax option to show up. Here you can select a tax rate to apply to the expense if Taxes > By Rate is selected in the expense, or enter the tax name and tax amount if Taxes > By Amount is selected in the expense.
  • NOTE that you select the tax rate/amount here on the left, but control how the tax is applied on the right under the Taxes panel based tax, to a custom flat tax.
• Amount: enter the total expense amount
• Currency: Currency you paid your expense in, automatically populated with the default currency of the vendor assigned to the expense. If not specified, currency is treated as your default company currency.
• Date: Date of the expense (defaults to today). Note that this is the date that the vendor invoices you for the expense, not the date of your payment to the vendor.

Notes

• Public Notes - Use this field to describe the expense. When creating an invoice for a client from an expense record, the public notes are included in the line item description for the expense.
• Private Notes - The value of this field is only viewable by users of the admin portal, so you can use it to make notes to yourself and other coworkers about the expense record.

Additional Info

• Should be invoiced: you can turn this toggle on if the expense should be invoiced to a client (see More Actions dropdown menu for next steps)
• Mark Paid: Enable this to indicate that your organization has paid the vendor for this expense. This is not to indicate a payment from a client. After checking Mark Paid, these options will appear below:
  • Payment Type: Select the payment type your organization used to pay the vendor with.
  • Date: Enter the date your organization paid the vendor (defaults to today).
  • Transaction Reference: Enter a transaction reference code or number if applicable.
• Convert currency: If the expense is billed in a currency other than your own default currency, enabling this allows you to set the currency you prefer to pay with, and an exchange rate, to calculate how much the expense cost in your preferred currency.
  • Exchange Rate: the current exchange rate will be automatically set when selecting a currency, but can be manually adjusted
  • Converted Amount: this amount is calculated as follows: Expense Amount * Exchange Rate = Converted Amount
• Add Documents to Invoice: Enable this feature to include any documents attached to an expense, with the documents attached to the invoice when you create an invoice out of the expense record.
• Taxes: configure how the expense is taxed to you in more detail.

Taxes

The taxes section is where you control how taxes are applied to the expense.

Expense Tax Rates must first be enabled under Settings > Tax Settings for expense taxes to work (or it will say "Item tax rates are disabled").

The Taxes panel on the bottom right of the expense edit screen will let you choose one of these options:

• Enter Taxes: Configure how the expense is taxed to you in more detail. Change between rate or amount to change the Tax field (under the details tab) from a percent based tax, to a custom flat tax.
  • By Rate: this is selected by default. You can select a tax rate under Details to apply to the expense.
  • By Amount: allows you to manually enter a Tax Name and Tax Amount under Details to apply to the expense. Note that you can apply up to three tax rates/amounts to an expense, based on the settting Settings > Tax Settings > Expense Tax Rates where you can select Disabled, One Tax Rate, Two Tax Rates, or Three Tax Rates. For example, if you have Three Tax Rates as the enabled option, you will see three Tax options on the left.
• Inclusive Taxes: Enable this option if the taxes are inclusive to the cost of the expense, rather than exclusive. For example:
  • Exclusive tax is applied on top of the expense cost, like so: 100 + 10% = $110 total (100 + 10).
  • Inclusive tax is when taxes are deducted from the amount the vendor bills you, and included in your expense amount, rather than tacked on top of what you pay the vendor, like so: 100 + 10% = $100 total (90.91 +9.09).

Here's a video of enabling the Expense Tax Rates, adding a new Expense Category, and recording a new expense using these options:

More Actions dropdown menu

You can use the More Actions dropdown menu (if on the expenses table view) or the Save dropdown arrow menu in the top right corner of the expense edit panel, to see a list of management actions that can be taken against the expense record:

• Clone: this will create a new expense record with the same details as the existing expense record, for today's date.
• Clone to Recurring: clone the expense record to a new recurring expense
• Archive
• Delete
• Restore: only visible if an archived/deleted expense is selected - lets you restore the expense to logged/paid status

These additional options will be visible only if Should be invoiced is checked:

• Invoice Expense: this will create a new invoice record with the expense details automatically entered as a line item on the invoice
• Add to Invoice: this will let you add the expense to an existing invoice with the expense details automatically entered as a line item on the invoice. A list of the client's invoices will show for selection.

Documents

The Documents tab supports uploading files such as documents, pictures, and more to allow you to share them with the client when attached to an invoice (if enabled) or with other users of the admin portal.

Lifecycle of an Expense

The following describe the lifecycle of an expense record

Logged

An expense's default state is Logged, when an expense is created. An expense is marked logged whether or not you have reported that you have paid the vendor for the expense yet.

Pending

An expense that has Should be Invoiced enabled, making it billable to a client, is automatically changed to a Pending state.

Invoiced

An expense record is automatically changed to Invoiced after the expense has been added to a client invoice. Note that an expense is marked Invoiced simply by being on an invoice, and its state doesn't change whether or not that invoice has been paid for by the client. The overview tab of the expense record's preview panel will link you to the invoice that expense is attached to.

Archived

An expense record can manually be archived, which simply hides it from view in the table or list of active expenses. The details of archived expenses are still included in reports. You can view archived expenses by changing filters in the table view, and you can use the "Restore" function to return an archived expense to its former state.

Deleted

An expense record can manually be deleted, which will remove it from view, and remove it from any reports as well. Deleted expense records can be seen by changing your filters when viewing the table or list of expenses, and using the "Restore" function can return the deleted expense record to its former state.

Tips

• You could just create an expense only with an amount and nothing else... but it's best to always organize your expenses by vendor/client. For example, under Reports you're able to report on expenses by status, clients, vendors, projects, and categories. Also, expenses will be shown in categories under the Profit and Loss report.
• You can see all expenses attached to a specific vendor: Vendor Details > Expenses
• You can see all expenses attached to a specific client: Client Details > Expenses
• Expenses can have default options configured under Settings > Expense Settings. See Expense Settings

Expense Inbound Email (Self Host Only)

This feature allows you to configure an e-mail address to accept attachments from vendors, clients and internal users which can then be processed using Mindee to perform data extraction and create expense records. Zugferd xml files are also supported and are able to be automatically parsed and converted into an expense.

The system works by configuring an e-mail address to accept attachments, the attachments (and the email body text) are stored on file and an expense record is created. The system will attempt to extract data from the document and insert it into the expense record.

The following settings are available:

• Enable Expense Mailbox (Enabled/Disables the processing of emails)
• Expense Mailbox E-Mail (The e-mail address to process which will be receiving the emails)
• Allow Company Users (Toggles whether internal users can send emails to the configured expense mailbox)
• Allow Vendors (Toggles whether vendors can send emails to the configured expense mailbox)
• Allow Unknown Senders (Toggles whether unknown semders can send emails to the configured expense mailbox)
• Allowed Email Addresses (A comma separated list of domains which are allowed to send emails to the configured expense mailbox)
• Blocked Email Addresses (A comma separated list of domains which are blocked from sending emails to the configured expense mailbox)

Inbound Providers

Mailgun

To ensure delivery, you have to configure all used mailgun regions with a recieving configuration using store & notify.

Create and setup your mailgun account Prepare your DNS settings for inbound mail processing, by setting up necessary MX records Create a receiving route using store and notify 3a. Go to Receiving Section and click on "Create Route" 3b. Create your route by selecting your mailbox configured in invoiceninja and add notify endpoint /api/v1/mailgun_inbound_webhook

Brevo

To ensure delivery you have to configure brevo inbound parsing according to: https://developers.brevo.com/docs/inbound-parse-webhooks

Create and setup your brevo account Prepare your DNS settings for inbound mail processing, by setting up necessary MX records Register the webhook via the brevo api to the following notify endpoint: /api/v1/brevo_inbound_webhook?token=brevo-api-token SetUp Postmark To ensure delivery you have to configure brevo inbound parsing according to: https://developers.brevo.com/docs/inbound-parse-webhooks

SetUp with Own MailServer

If you want to use your own mailbox, you have to either redirect the mail to a mailbox of one of the providers above or use a provider for inbound directly. We recommend to use one of these providers hosted on a subdomain f.ex. invoicing.xxx.com directly or to use the auto-generated mailbox of postmark when you are using redirect.

SetUp Mindee OCR

To parse a document IN can use OCR solutions like Mindee. Mindee offers to process documents and guess the contents using AI. Each account has 250 pages for free, which makes it very suiteable for small busineses using self-hosted.

Use the following .env variable to configure your mindee api key:

MINDEE_API_KEY=your-api-key

1. (Optional) SetUp Mindee Account and Update ENV

First of All, you have to create your Mindee Account (if you wanna use OCR), without it IN will only use standards like ZUGFeRD if the document supports it. Create an API Key and save it to the env file of your IN instance: MINDEE_API_KEY=API-KEY I suggest checking how many free pages are included in your free mindee subscription. Default should be 250, but this may varry. I you wanna change your local tracked contingent per month to avoid unnecessary payments to mindee, you can use the following envs to customize the behavior:

MINDEE_MONTHLY_LIMIT MINDEE_DAILY_LIMIT MINDEE_ACCOUNT_MONTHLY_LIMIT MINDEE_ACCOUNT_DAILY_LIMIT if the limit is exceeded mindee is treated as not configured. (ignored)

2. SetUp your Inboud Mail Provider

SetUp your account at mailgun/postmark/brevo and follow the steps to setup inbound mail parsing (each service does it differently) You can look at the original PR (#9042) , where I have documented more informations about each provider. I will now describe how I did it with brevo: a) Set an API-Key for the brevo endpoint within your env: INBOUND_WEBHOOK_TOKEN=XXX you can use somthing like: https://generate-random.org/api-key-generator b) Read and do this (setup your DNS and infos about it): https://developers.brevo.com/docs/inbound-parse-webhooks c) Create an API key in the Console d) Use this api-documentation to send the needed requests to setup your webhook: https://developers.brevo.com/reference/getwebhooks-1 => please append the following at the end of your url ?token=XXX (this is the api token from a) I highly suggest trying it first out if the webhook is working by using an url from https://webhook.site. This website will show you the contents of the webhooks beeing send, after you sended an email to the inbound webhook email. You can use the recieving url as the target for the webhooks created in d)

3. (Optional) Prepare your current email mailbox

I am using gmail with google workspace, so i created a forward rules within admin.google.com to redirect all emails from xxx@my-domain.de to my internal email at brevo for recieving email at brevo and dont publishing the brevo email. You can also use the rules for redirect within the mailbox itself

4. SetUp IN

a) Go To Settings->Expenses and enable the Inbound Mailbox b) Paste your brevo email into the reciever field (this has to be unique regarding the whole IN instance) c) Allow the senders you want to be able to send you expenses via mail. => I use enable my vendors and from my own company and added as whitelist also my personal email from my phone

5. Test the system

a) Send an Email to the brevo inbound email b) Check if an expense got created c) If not: check if the request from brevo is present => this sometimes takes up to 5min d) If yes: check the logs for any errors and report them as an issue if you have any trouble resolving them