Tip
This extension is actively used in a production EspoCRM instance. Feature requests and bug reports are welcome via GitHub Issues and will be reviewed within 1–3 weeks.
Warning
EspoCRM Finance is a personal finance manager packaged as an EspoCRM extension. It adds two record types — Payments and Debts — plus a Finance dashboard that projects your cash flow, breaks spending down by category, tracks debt repayment progress, and lists what is due in the next 30 days.
It is built for the private side of an EspoCRM instance: recurring and one-time payments in both directions, money you owe and money owed to you. Everything is computed in the browser from the ordinary record API, and every chart is drawn locally as plain SVG — no chart library, no CDN, no external requests, and no activity stream on the finance records.
The extension installs like any other EspoCRM extension package, registers its own navigation group, and removes it again cleanly on uninstall.
A focused set of tools for keeping track of private cash flow, covering payments, debts, forecasting, and reporting — without unnecessary complexity.
A Payment record covers both directions and both rhythms. Each payment has a name, an amount in the instance's currency, a direction (Incoming / Outgoing), a type (Recurring / One-time), a start or due date, an optional end date, a category, an active flag, and a free-text description for IBANs, contract numbers, or notes. Direction and type are rendered as coloured labels in list and detail views.
Recurring payments repeat every n days, weeks, months, or years, configured through the Every and Interval fields (1–240 intervals). Monthly and yearly recurrences keep their anchor day and clamp correctly to shorter months, so a payment due on the 31st still lands on the last day of February. An optional end date stops a series from being projected any further.
A Debt record tracks a Payable (you owe) or Receivable (owed to you) amount against a named counterparty, with a total, a paid amount, an optional due date, and a description. Remaining amount and the settled flag are derived server-side by an ORM hook on every save: the paid amount is clamped into [0, total], remaining is total − paid, currencies are kept in sync, and a debt is marked settled as soon as the remainder falls below one cent.
A dedicated dashboard scope with four KPI tiles — monthly incoming, monthly outgoing, monthly net (all from recurring items only), and open debt with the receivable counter-sum. Below them sit the cash flow forecast, the category breakdown, debt progress, and the upcoming payments list.
A grouped bar chart of projected incoming and outgoing amounts per month, with a net line drawn on top. The horizon is switchable between 6M, 12M, and 24M from the dashboard header. Recurrences are expanded month by month across the selected window, and hovering a bar shows the exact figures in a tooltip.
A donut chart plus a legend of every outgoing category in the selected window, sorted by amount and showing each category's share as a percentage. Fifteen categories are available — Housing, Utilities, Insurance, Subscription, Transport, Groceries, Health, Leisure, Education, Taxes, Loan, Salary, Investment, Refund, Other — and uncategorized spending is reported separately. Each category keeps a stable colour between renders.
Open debts are listed with a progress bar of paid-versus-total, plus direction, counterparty, and due date, sorted by the largest remaining amount. Next to it, every occurrence falling into the next 30 days is listed by date with a signed amount, linked straight to the underlying record.
All charts inherit currentColor and translucent greys, so the dashboard follows whichever Espo theme is active, light or dark. Amounts are formatted with Intl.NumberFormat in the instance's default currency, and month and day labels with Intl.DateTimeFormat in the user's language. The layout is responsive and redraws on window resize and container resize alike.
The extension ships with full en_US and de_DE translations for all entities, fields, options, tooltips, and dashboard labels.
The dashboard issues nothing but ordinary authenticated record API calls against your own EspoCRM instance. There are no CDN references, no web fonts, no analytics, and no telemetry. The stream is disabled on both entity types, so no finance activity is written to the audit stream.
The extension runs inside an existing EspoCRM installation and adds no dependencies of its own.
| Requirement | Value |
|---|---|
| EspoCRM | 8.0.0 or newer |
| PHP | 8.1 or newer |
| Modern Browser (Chrome, Firefox, Edge, Safari) | Required |
| JavaScript enabled | Required |
| Composer / npm dependencies | None |
| Internet connection at runtime | Not required |
Download the latest Finance-x.y.z.zip from the _releases/ folder or from the GitHub Releases page, then in EspoCRM go to Administration → Extensions, upload the ZIP, and confirm the installation.
The installer adds a Finance navigation group containing the Finance dashboard, Payments, and Debts. Uninstalling removes those entries again and drops the group if it ends up empty.
Copy the contents of _source/files/ over your EspoCRM root, so that custom/Espo/Modules/Finance/ and client/custom/modules/finance/ land in place. Then run:
php rebuild.phpAdd FinanceDashboard, FinanceEntry, and FinanceDebt to the tab list manually under Administration → User Interface, and grant access to the scopes under Administration → Roles.
- Open the Finance tab and use Add Payment on the empty state.
- Create your recurring outgoings — rent, utilities, subscriptions — and your recurring income.
- Add one-time payments for anything with a single due date.
- Record open debts under Debts, updating the paid amount as you pay them off.
- Switch the forecast between 6M, 12M, and 24M, and use Refresh after bulk edits.
The category list is a plain enum, so a new category can be added by editing two files under _source/files/custom/Espo/Modules/Finance/Resources/.
Add the key to the category field options in metadata/entityDefs/FinanceEntry.json:
"category": {
"type": "enum",
"options": [
"",
"Housing",
"Pets",
"Other"
],
"default": null
}Add the same key to the options.category block of every language file under i18n/, for example i18n/en_US/FinanceEntry.json:
"category": {
"Pets": "Pets"
}Run php rebuild.php afterwards. The donut chart picks the new category up automatically and assigns it a colour from the built-in palette; the fixed CATEGORIES array in client/custom/modules/finance/src/views/dashboard/index.js only pins the colours of the shipped categories, and anything beyond it falls back to the shared palette.
| Path | Description |
|---|---|
| .git/ | Internal file, can be ignored. |
| .github/ | Internal file, can be ignored. |
| _changelogs/ | HTML changelogs per released version. |
| _licenses/ | Licenses of third-party components. |
| _releases/ | Built extension packages, ready to upload to EspoCRM. |
| _source/ | Extension source: manifest, install scripts, and the files/ tree. |
| _source/files/custom/ | Server side — controllers, the debt hook, metadata, layouts, and translations. |
| _source/files/client/ | Client side — dashboard view, chart renderer, helpers, and template. |
| README.md | This readme file. |
| CHANGELOG.md | Changelog overview. |
| LICENSE.md | License file. |
| THIRD-PARTY-LICENSES.md | Third-party components and their licenses. |
If you encounter any issues or have questions while using this software, feel free to contact us:
- GitHub Issues is the main platform for reporting bugs, asking questions, or submitting feature requests: https://github.com/bugfishtm/espocrm-finances/issues
- Discord Community is available for live discussions, support, and connecting with other users: Join us on Discord
- Email support is recommended only for urgent security-related issues: security@bugfish.eu
Help us grow by sharing this project with others! You can:
- Tweet about it – Share your thoughts on Twitter/X and link us!
- Post on LinkedIn – Let your professional network know about this project on LinkedIn.
- Share on Reddit – Talk about it in relevant subreddits like r/espocrm or r/opensource.
- Tell Your Community – Spread the word in Discord servers, Slack groups, and forums.
Thank you for your interest in this project.
At this time, this repository is not open for external contributions. Please do not submit pull requests or patches.
- Pull requests from external contributors are not accepted.
- Any unsolicited pull requests will be closed without review.
- All code in this repository is maintained by the project owner.
- By design, no third‑party code will be merged into this project via GitHub.
If you encounter a bug or have an enhancement suggestion, please check the "Issues" section of our GitHub repository or visit our official website for guidance before beginning any work on it.
We're focused on developing innovative solutions and advancing technology. By being part of this, you contribute to our progress.
Positive guidelines include being kind, empathetic, and respectful in all interactions. It is important to engage thoughtfully and offer constructive, solution-oriented feedback. Fostering an environment of collaboration, support, and mutual respect is essential.
Unacceptable behaviors include harassment, hate speech, or offensive language. Personal attacks, discrimination, or any form of bullying are not tolerated. Sharing private or sensitive information without explicit consent is strictly prohibited.
Together, we can partner to achieve common goals by following guidelines designed to promote effective collaboration and positive teamwork.
I take security seriously and appreciate responsible disclosure. If you discover a vulnerability, please follow these steps:
- Do not report it via public GitHub issues or discussions. Instead, please contact the security@bugfish.eu email address directly.
- Provide as much detail as possible, including a description of the issue, steps to reproduce it, and its potential impact.
I aim to acknowledge reports within 2–4 weeks and will update you on our progress once the issue is verified and addressed.
This software is provided as-is, without any guarantees of security, reliability, or fitness for any particular purpose. We do not take responsibility for any damage, data loss, security breaches, or other issues that may arise from using this software. By using this software, you agree that We are not liable for any direct, indirect, incidental, or consequential damages. Use it at your own risk.
This extension is licensed under the GNU General Public License v3, matching EspoCRM, the platform it is built on. The full text can be found in the LICENSE.md file. Third-party components and their licenses are documented in _licenses/THIRD-PARTY-LICENSES.md.
🐟 Bugfish