---
title: "GrowthInvoices Documentation"
description: "Technical documentation for GrowthInvoices — a self-hosted invoicing plugin for small Spanish businesses and freelancers. This page covers how the plugin works, setup, the shortcode, roles, the docume..."
url: https://growthplugins.com/docs/growthinvoices/
date: 2026-11-17
modified: 2026-11-17
author: "GrowthPlugins"
type: page
lang: en
---

# GrowthInvoices Documentation

*Technical documentation for **GrowthInvoices** — a self-hosted invoicing [plugin](https://growthplugins.com/) for small Spanish businesses and freelancers. This page covers how the plugin works, setup, the shortcode, roles, the document workflow, numbering, the Spanish tax engine, reports, the data model, and the AI / MCP abilities layer.*

**Version:** 0.1.6  |  **Requires:** WordPress 6.4+, PHP 8.1+  |  **Text domain:** `growth-invoices`

## 1. Overview — how it works

GrowthInvoices manages invoices, quotes, rectificative invoices, clients, a product/service catalog and payments inside WordPress. It is **standalone**: no WooCommerce dependency and no custom post types. Everything lives in its own tables (prefix `gi_`).

Design principles:

- **Money as integer cents.** Every amount is stored in `*_cents` columns to avoid floating-point rounding errors.
- **Server-side totals.** Totals are always recomputed on the server by the tax engine; the totals you see while editing are only a live preview.
- **Audit trail.** Every relevant change (drafts, issuing, status changes, conversions, payments, deletions) is written to an event log — the foundation for VeriFactu [support](https://growthplugins.com/plugin/growthsupport/) (see [section 10](#verifactu)).

The plugin exposes three interfaces on top of the same services:

- **wp-admin** — a top-level *GrowthInvoices* menu.
- **Front end** — the same app on any page via the `[growthinvoices_app]` shortcode, ideal for a private intranet.
- **AI abilities** — WordPress Abilities API tools, optionally exposed over MCP.

Sections: Dashboard · Invoices · Quotes · Clients · Products & Services · Reports · Settings.

## 2. Installation & setup

1. Upload and activate the plugin. On activation it creates the tables (see [section 8](#data-model)), grants the `manage_growth_invoices` capability to administrators and stores default settings.
2. Go to **GrowthInvoices → Settings** and fill in your **company details** (name, tax ID/NIF, address, email, phone, registry data) and upload your **logo**.
3. Review **VAT rates**, **IRPF**, **document series** and the **number format** ([section 6](#numbering)), plus default terms and due dates.
4. Optionally, choose or create the **front-end page** ([section 3](#shortcode)).
5. Add your first client and create a quote or invoice.

Schema upgrades run automatically on load, so updating the plugin does not require re-activation.

## 3. Shortcode (front-end app)

```
[growthinvoices_app]
```

Renders the full app — the same screens as wp-admin — on any page. In **Settings → Front-end page** you can either select an existing page that contains the shortcode or create one automatically. No page is forced.

- Access requires being logged in **and** having the `manage_growth_invoices` capability.
- Front-end navigation uses `gi_`-prefixed query parameters (`?gi_view=&gi_action=…`) to avoid clashing with WordPress reserved query vars.
- Forms post to `admin-post.php` and redirect back to the page you came from, so the same handlers serve both the front end and wp-admin.

## 4. Roles & capabilities

| Capability | Grants | Default roles |
| --- | --- | --- |
| `manage_growth_invoices` | Full access to the app in wp-admin and on the front end. | Administrator |

To let an accountant or office manager use GrowthInvoices without making them an administrator, grant their role `manage_growth_invoices` (for example with a role-editor plugin or `$role->add_cap()`). AI abilities use their own configurable capability ([section 9](#abilities)).

## 5. Documents & workflow

### Document types

| Type | Default series | Statuses |
| --- | --- | --- |
| Invoice | `F` | draft → issued → partial / paid; or cancelled |
| Quote | `P` | draft → sent → accepted / rejected → invoiced |
| Rectificative invoice | `R` | draft → issued → partial / paid |

### Lifecycle

- **Drafts** have no number. They can be edited freely and do not reserve a slot in the numbering sequence.
- **Issuing** an invoice or rectificative allocates its definitive correlative number, sets the issue and due dates (default due date: issue date + 30 days), records the issue time and logs the event. You can also save and issue in one step.
- **Quote → invoice:** converting an accepted quote creates a draft invoice with the same client and lines, and marks the quote as *invoiced*.
- **Rectificative invoices:** created from an issued invoice as a draft with the same lines and **negated quantities**, linked to the original through `rectifies_id`.
- **Payments:** record one or more payments (date, amount, method, reference) against an issued invoice. Its status is recalculated automatically: no payments → *issued*, partial amount → *partial*, full amount → *paid*.
- **Email:** send any document as an HTML email (via `wp_mail`) from your company name and email, with an optional custom subject and message. Emailing a draft quote marks it as *sent*.
- **PDF:** each document has a print view styled with your logo and brand colors, ready for the browser’s *Save as PDF*.

## 6. Numbering

Numbers are **correlative and gap-free** per document type and series. Allocation uses a MySQL named lock, so two people issuing invoices at the same time never get the same number.

- **Series per type** — configurable prefixes (defaults: `F` invoices, `R` rectificatives, `P` quotes).
- **Yearly reset** — enabled by default: the year becomes part of the series, so numbering restarts at 1 every year.
- **Number format** — a template with placeholders. Default: `{series}{yyyy}-{n:04}` → `F2026-0001`.
- **Starting number** — you can set the next number for a type (useful when migrating from another tool mid-year). It is used once and then cleared.

| Placeholder | Output |
| --- | --- |
| `{series}` | Series prefix (e.g. `F`) |
| `{yyyy}` / `{yy}` | 4- or 2-digit year |
| `{n}` | Number with the default padding |
| `{n:03}` | Number padded to 3 digits (`012`) |

## 7. Spanish tax engine & reports

### VAT (IVA)

A configurable list of rates (default 21%, 10%, 4%, 0%). The rate is set **per line**, so one invoice can mix rates; the document groups the tax bases by rate and prints the breakdown. Line discounts (%) are applied before VAT.

### Equivalence surcharge (recargo de equivalencia)

Optional per client and per document. Each VAT rate maps to a surcharge rate (defaults: 21% → 5.2%, 10% → 1.4%, 4% → 0.5%), calculated on the aggregated base for that rate.

### IRPF withholding

Optional per client (default rate) and per document. The default rate is 15%. IRPF is calculated on the total tax base and subtracted from the invoice total.

**Total** = tax base + VAT + equivalence surcharge − IRPF.

### Reports

- **Dashboard KPIs** — billed this year and this month, outstanding amount, overdue invoices and open quotes.
- **Quarterly summary** — tax base, VAT and IRPF per quarter, aligned with Spanish forms 303 (VAT) and 130/111 (IRPF).
- **VAT by rate** for the year, plus **monthly income** and **top clients**.

Only issued invoices and rectificatives count towards reports; drafts and quotes do not.

## 8. Data model

Six tables are created (with the site’s table prefix):

| Table | Contents |
| --- | --- |
| `{prefix}gi_clients` | Name, tax ID, contact details, address, country, default IRPF and equivalence-surcharge flags, notes. |
| `{prefix}gi_products` | SKU, name, description, unit price (cents), VAT rate, unit, active flag. |
| `{prefix}gi_documents` | Type, series, number, full number, status, a **snapshot of the client’s data** at the time of the document, dates, tax settings, totals in cents, per-rate tax summary, notes, terms, links (`rectifies_id`, `converted_from_id`), `issued_at`. Unique key on (type, series, number). |
| `{prefix}gi_document_lines` | Position, product, concept, description, quantity, unit price, discount %, VAT rate, computed base/VAT/total. |
| `{prefix}gi_payments` | Document, amount (cents), paid date, method, reference, notes. |
| `{prefix}gi_event_log` | Object type and ID, action, user, JSON data, timestamp. |

Because client data is copied onto each document, editing a client later never changes invoices you have already issued.

Settings are stored in the `growthinvoices_settings` option.

## 9. AI abilities & MCP

GrowthInvoices registers **18 abilities** on the **WordPress Abilities API** (WordPress 6.9+), in five categories. On older WordPress versions this layer is simply skipped.

| Category | Abilities |
| --- | --- |
| Documents | `list-documents`, `get-document` (read-only); `create-document`, `update-document`, `issue-document`, `convert-quote-to-invoice`, `create-rectificative` |
| Clients | `list-clients`, `get-client` (read-only); `create-client`, `update-client` |
| Products | `list-products`, `get-product` (read-only); `create-product`, `update-product` |
| Payments | `record-payment` |
| [Finance](https://growthplugins.com/plugin/growthbalance/) & config | `financial-summary`, `get-settings` (read-only) |

All abilities live under the `growthinvoices/*` namespace and declare JSON input/output schemas. That lets an assistant handle requests such as “invoice client X for 10 hours of consulting at €60”, “which invoices are overdue?” or “how much VAT do I owe this quarter?”. No ability deletes data.

### Permissions & MCP visibility

- Every ability requires `manage_options` by default.
- All abilities are *MCP-public* by default (none are destructive).
- The required capability and MCP visibility of each ability (or a whole category) can be overridden from the plugin’s Abilities settings, stored in the `growthinvoices_abilities_config` option. Per-ability overrides take precedence over category defaults, which take precedence over the code defaults.

## 10. VeriFactu status

The data model is designed to be **VeriFactu-ready**: gap-free numbering, client snapshots on each document, rectificatives instead of silent edits, and an event log of every change. **Submission to the AEAT is not included yet.** It is planned for a later release (chained record hashes, verifiable QR code on the PDF, digital certificate and a submission queue).

## 11. FAQ & troubleshooting

#### Do I need WooCommerce?

No. GrowthInvoices is standalone and does not depend on WooCommerce or any other plugin.

#### Which languages does it support?

The interface is in English with a full Spanish (`es_ES`) translation. In Settings you can force English, force Spanish or follow the WordPress site language.

#### The front-end page shows an access error.

The user must be logged in and have the `manage_growth_invoices` capability. Administrators have it by default; grant it to other roles as needed.

#### How do I get a PDF?

Open the document’s print view and use your browser’s *Print → Save as PDF*. The layout uses your logo and brand colors.

#### I’m migrating mid-year. Can I continue my numbering?

Yes. Set the next number for each document type in Settings; the next issued document will use it.

#### What happens to my data if I uninstall the plugin?

Nothing, by default: fiscal records are kept. Tables and settings are only removed on uninstall if you explicitly opt in, either by defining `GROWTHINVOICES_PURGE_ON_UNINSTALL` as `true` in `wp-config.php` or by setting the `growthinvoices_purge_on_uninstall` option to `yes`.

---

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