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 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
*_centscolumns 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 (see section 10).
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
- Upload and activate the plugin. On activation it creates the tables (see section 8), grants the
manage_growth_invoicescapability to administrators and stores default settings. - Go to GrowthInvoices → Settings and fill in your company details (name, tax ID/NIF, address, email, phone, registry data) and upload your logo.
- Review VAT rates, IRPF, document series and the number format (section 6), plus default terms and due dates.
- Optionally, choose or create the front-end page (section 3).
- 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_invoicescapability. - Front-end navigation uses
gi_-prefixed query parameters (?gi_view=<section>&gi_action=…) to avoid clashing with WordPress reserved query vars. - Forms post to
admin-post.phpand 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).
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:
Finvoices,Rrectificatives,Pquotes). - 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 & 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_optionsby 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_configoption. 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.