---
title: "GrowthBalance Documentation"
description: "Technical documentation for GrowthBalance — a project profitability tracker for freelancers, agencies and side-projects. This page covers how the plugin works, setup, the shortcode, the calculation mo..."
url: https://growthplugins.com/docs/growthbalance/
date: 2026-11-17
modified: 2026-11-17
author: "GrowthPlugins"
type: page
lang: en
---

# GrowthBalance Documentation

*Technical documentation for **GrowthBalance** — a [project profitability tracker](https://growthplugins.com/plugin/growthbalance/) for freelancers, agencies and side-[projects](https://growthplugins.com/plugin/growthprojects/). This page covers how the [plugin](https://growthplugins.com/) works, setup, the shortcode, the calculation model, integrations with GrowthProjects and GrowthInvoices, the data model, and AJAX actions.*

**Version:** 1.1.0  |  **Requires:** WordPress 6.0+, PHP 7.4+  |  **Text domain:** `growthbalance`

## 1. Overview — how it works

GrowthBalance answers one question per project: *is this worth my time?* For each project you record income, expenses and hours worked; the plugin turns them into a monthly series, a cumulative balance, an **effective hourly rate** and a set of viability messages.

- **100% front end** — the whole app runs from the `[growthbalance]` shortcode. wp-admin only holds a small settings screen to choose the app page.
- **Private per user** — every project, movement and hours record belongs to the WordPress user who created it. Each logged-in user sees only their own data.
- **Optional integrations** — link a project to a GrowthProjects workspace (hours) and/or a GrowthInvoices client (income) and those figures are pulled in automatically, read-only.

## 2. Installation & setup

1. Upload and activate the plugin. On activation it creates three database tables (see [section 6](#data-model)).
2. Go to **GrowthBalance → Settings** in wp-admin and either **create the app page** automatically (it is published with the shortcode inside) or **assign an existing page** that already contains it.
3. Open that page while logged in and create your first project.

The settings screen requires `manage_options`. Using the app itself only requires being logged in.

## 3. Shortcode

```
[growthbalance]
```

The legacy alias `[freelance_balance]` renders the same app.

- Visitors who are not logged in see a notice asking them to log in.
- Logged-in users see the **dashboard**: global KPIs, charts and a table with every project (balance, hours this month vs. target, effective €/h).
- Adding `?gb_project={id}` to the page URL opens the **project detail** view: KPIs, income/expense and cumulative-balance charts, viability analysis, the hours log and the list of movements. Clicking a project in the dashboard does this for you.

Charts are rendered with Chart.js 4, loaded from the jsDelivr CDN. Assets are only enqueued on pages that render the shortcode.

## 4. Projects, movements & the calculation model

### Projects

| Field | Values / notes |
| --- | --- |
| Type | Client project or side-project |
| Status | Active, Paused, Archived |
| Target €/h | Hourly rate you aim for; compared against the effective rate |
| Target hours/month | Shown next to the hours logged this month |
| Color | Used in charts and tables |
| Links | Optional GrowthProjects workspace and GrowthInvoices client ([section 5](#integrations)) |

### Movements (income & expenses)

Each movement has a kind (income or expense), amount, concept, date and a **recurrence**, which decides how it is spread over months:

| Recurrence | How it is counted |
| --- | --- |
| One-off | The full amount in the month of its date. |
| Monthly | The full amount every month from its date until its end date (or indefinitely). |
| Yearly | Amortized as *amount ÷ 12* every month from its date until its end date (or indefinitely). |

This monthly-equivalent model means a €120/year hosting plan shows up as a €10/month cost, so side-projects with annual subscriptions are compared fairly against monthly income.

### Hours

Hours are logged **per project and per month** (one record per month, with an optional note). If the project is linked to a GrowthProjects workspace, the tracked hours from that workspace replace the manual ones.

### Metrics

- **Balance** = total income − total expenses, from the first month with data until the current month.
- **Cumulative balance** — running total month by month (the “have I recovered the investment yet?” line).
- **Effective €/h** = balance ÷ total hours.
- **Monthly recurring net** — recurring income minus recurring expenses active in the current month.

### Viability analysis

The project detail view turns those numbers into plain-language messages, for example:

- Losing *X*/month in recurring costs, and how many months the current balance covers (**runway**).
- Generating *X*/month of net recurring income (sustainable project).
- Negative accumulated balance: the investment has not been recovered yet.
- Effective €/h below or above your target rate.

## 5. Integrations

Integrations are **read-only** and detected at runtime: GrowthBalance never writes to the other plugins’ tables. The link fields only appear when the other plugin is installed.

| Plugin | Link a project to | What is imported |
| --- | --- | --- |
| [GrowthProjects](https://growthplugins.com/plugin/growthprojects/) | A workspace | Monthly hours: the sum of completed time entries on every task in that workspace (including tasks inside its folders and lists). Replaces manual hours for that project. |
| [GrowthInvoices](https://growthplugins.com/plugin/growthinvoices/) | A client | Monthly income: the total of that client’s [invoices](https://growthplugins.com/plugin/growthinvoices/) with status issued, partially paid or paid, grouped by issue date. Drafts, quotes and proformas are excluded. Added on top of manual income movements. |

Together they close the loop: hours tracked in GrowthProjects and invoices issued in GrowthInvoices give you the real effective hourly rate of each client without entering anything twice.

## 6. Data model

Three tables are created (with the site’s table prefix). Every row stores a `user_id` and all queries are scoped to the current user.

### Table: `{prefix}fb_projects`

| Column | Type | Notes |
| --- | --- | --- |
| id / user_id | BIGINT | Owner is the WordPress user |
| name / description | VARCHAR(191) / TEXT | |
| type | VARCHAR(20) | `cliente` \| `sideproject` |
| status | VARCHAR(20) | `activo` \| `pausado` \| `archivado` |
| hourly_rate / monthly_hours_target | DECIMAL | Targets |
| color | VARCHAR(7) | Hex color |
| gproj_workspace_id / gi_client_id | BIGINT | Optional integration links (0 = none) |
| created_at | DATETIME | |

### Table: `{prefix}fb_transactions`

| Column | Type | Notes |
| --- | --- | --- |
| id / project_id / user_id | BIGINT | |
| kind | VARCHAR(10) | `ingreso` (income) \| `gasto` (expense) |
| amount | DECIMAL(12,2) | Always stored as a positive value |
| concept | VARCHAR(191) | |
| recurrence | VARCHAR(10) | `unico` \| `mensual` \| `anual` |
| txn_date / end_date | DATE | `end_date` only for recurring movements |
| created_at | DATETIME | |

### Table: `{prefix}fb_hours`

| Column | Type | Notes |
| --- | --- | --- |
| id / project_id / user_id | BIGINT | |
| period | VARCHAR(7) | `YYYY-MM`; unique per project |
| hours | DECIMAL(7,2) | |
| note | TEXT | |

The `fb_` prefix and the Spanish enum values come from the plugin’s origins as “Freelance Balance”; they are kept for backward compatibility. Deleting a project also deletes its movements and hours.

## 7. AJAX actions

All writes go through `admin-ajax.php`. Every action is logged-in only, requires the nonce field `nonce` for action `gbal_nonce`, and only touches records owned by the current user.

| Action | Purpose | Key POST fields |
| --- | --- | --- |
| `gbal_save_project` | Create or update a project | `id` (optional), `name`, `description`, `type`, `status`, `hourly_rate`, `monthly_hours_target`, `color`, `gproj_workspace_id`, `gi_client_id` |
| `gbal_delete_project` | Delete a project and all its data | `id` |
| `gbal_save_transaction` | Create or update a movement | `id` (optional), `project_id`, `kind`, `amount`, `concept`, `recurrence`, `txn_date`, `end_date` |
| `gbal_delete_transaction` | Delete a movement | `id` |
| `gbal_save_hours` | Set the hours for a month (upsert) | `project_id`, `period` (`YYYY-MM`), `hours`, `note` |
| `gbal_delete_hours` | Delete an hours record | `id` |

## 8. FAQ & troubleshooting

#### The page says I must log in.

The app is per user, so it needs an authenticated WordPress user. Place the page behind login or send users to `wp-login.php` first.

#### Can my team share the same projects?

No. Data is private per WordPress user: each person who logs in gets their own independent set of projects. This makes it suitable for multi-user sites, but not for a shared team ledger.

#### I don’t see the GrowthProjects / GrowthInvoices link fields.

They only appear when the other plugin is active and has at least one workspace (GrowthProjects) or client (GrowthInvoices) to link to. Install and activate it, create a workspace or client, then edit the project again.

#### My manual hours disappeared after linking a workspace.

When a project is linked to a GrowthProjects workspace that has tracked time, those hours become the single source of truth and replace the manual ones. Unlink the workspace to go back to manual hours; your manual records are not deleted.

#### Which currency does it use?

Amounts are displayed in euros.

---

**Back to** [GrowthBalance product page](https://growthplugins.com/plugin/growthbalance/).
