Invoicing System
Overview
Section titled “Overview”The invoicing system manages the full lifecycle of club invoices — from creation through PDF generation, email delivery, and payment tracking. It supports discipline invoices, membership invoices, tournament invoices, and manual invoices.
Tournament invoices are created by a confirmed tournament entry, use the O number prefix, and
store _tournament_entry_id as their immutable domain link. They use the dedicated default Mollie
account configured for tournaments. The tournament entry exposes a permission-filtered derivative
of the invoice status; the invoice and verified Mollie webhook remain the financial source of truth.
Viewing invoices requires financieel_read; creating, sending, deleting or marking them paid requires financieel (which implies the read capability).
List Exports
Section titled “List Exports”The invoice overview at /financien/facturen can export its currently filtered and sorted rows as a semicolon-delimited, UTF-8 CSV file for Excel. The export is available to read-only financial users too and includes invoice number, customer and contact names, amount, type, displayed status, payment plan, sent/reminder dates, sender, and creation date.
The discipline-case overview at /tuchtzaken offers the same Excel-compatible export for the selected season and active filters. It includes dossier, person, match, team, card and charge details, sanction, charging status, and administrative fee.
Post Type
Section titled “Post Type”Invoices use the rondo_invoice custom post type with four custom post statuses:
| Status | Slug | Description |
|---|---|---|
| Draft | rondo_draft | Newly created, not yet sent |
| Sent | rondo_sent | Sent to member via email |
| Paid | rondo_paid | Payment confirmed (via Mollie webhook or manual) |
| Overdue | rondo_overdue | Past due date, not yet paid |
ACF Fields
Section titled “ACF Fields”Each invoice stores the following fields:
invoice_number— Unique formatted number (e.g.F2025-042orC2025-001)person— Relationship to thepersonpost typestatus— ACF status mirror (draft,sent,paid,overdue)invoice_type— Eitherdisciplineormembershiptotal_amount— Decimal totalline_items— Repeater field with sub-fields:discipline_case— Optional relationship to a discipline casedescription— Text description (used for membership line items)amount— Decimal amount (negative for discounts)
payment_link— Mollie checkout URL or public payment page URLpdf_path— Relative invoice PDF path, read-only in the field APIqr_code_path— Relative invoice QR image path, read-only in the field APIsent_date— Date invoice was sent (Ymd format)due_date— Payment due date (Ymd format)
Post Meta
Section titled “Post Meta”Additional metadata stored as raw post meta:
_mollie_payment_link_id— Mollie payment link ID (pl_xxx)_invoice_season— Season key (e.g.2025-2026) for membership invoices_payment_token— 64-char hex token for the public payment page_payment_account_id— Snapshotted Mollie account ID (or empty for non-Mollie flows)_payment_account_internal_name— Snapshotted account label_payment_account_account_holder— Snapshotted account holder_payment_account_iban— Snapshotted IBAN shown on the invoice/PDF_installment_plan— Payment plan choice (full,quarterly_3,monthly_8)_installment_count— Number of installments_installment_N_*— Per-installment meta (see Installments)
Invoice list and detail responses expose a canonical paid_at timestamp for fully paid invoices. It resolves to the manual paid timestamp, the final paid installment timestamp, or the direct Mollie payment timestamp. The invoice overview offers this value as the optional Betaald op column; the detail page always shows it with date and time when available.
Payment statistics include two current-season contribution charts. The invoice chart separates fully paid invoices, partially paid installment invoices, and invoices with no collected amount. The amount chart compares collected contribution principal with the total invoiced contribution principal; per-installment administration fees are excluded. Drafts, cancelled invoices, and credits are excluded from both distributions.
Scheduled sending and due dates
Section titled “Scheduled sending and due dates”Draft invoices can be scheduled with POST /rondo/v1/invoices/{id}/schedule, using
scheduled_send_date in YYYY-MM-DD or Ymd format. The invoice detail page and
bulk scheduling action use this endpoint. Dates must be today or later in the
WordPress site timezone; an empty value cancels the schedule.
Setting or updating a schedule recalculates due_date as the scheduled send date
plus the configured payment_term_days. The calculation uses calendar days in
the site timezone and clears any existing draft PDF so it can be generated with
the new due date. For example, 21 December with a 14-day term becomes 4 January.
The draft creation and editing form also moves its due-date field when the send date changes. The backend applies the same rule on creation or a changed send date. With an unchanged send date, an explicit due-date edit is preserved. Cancelling a schedule leaves the due date unchanged. Scheduling does not send an email immediately; the invoice remains a draft until the scheduled-send sweeper runs the normal sending flow.
Normal sends through POST /invoices/{id}/send reject future scheduled drafts
with HTTP 409 (invoice_send_scheduled) before generating payment links, PDFs,
or emails. To send early, explicitly cancel the schedule first. List and detail
responses expose scheduled_send_pending, calculated in the WordPress site
timezone, so the detail send button is disabled and bulk sending skips future
scheduled invoices while keeping them selected. Dates due today or earlier can
be sent normally. Preview emails with an explicit test recipient remain
available and preserve the draft and its schedule.
Invoice Numbering
Section titled “Invoice Numbering”Class: Rondo\Finance\InvoiceNumbering
Invoice numbers follow the format {PREFIX}{YEAR}-{SEQ} where:
- Discipline invoices: Prefix
F(e.g.F2025-001) - Membership invoices: Prefix
Cfor “contributie” (e.g.C2025-001)
Each prefix maintains an independent sequence counter per calendar year, stored in a WordPress option. The generate_next() static method accepts the invoice type and returns the next sequential number.
Numbering is gap-free within each prefix — the counter is incremented atomically.
Invoice Types
Section titled “Invoice Types”Discipline Invoices
Section titled “Discipline Invoices”Created manually via the REST API when a member receives fines from discipline cases (yellow/red cards). Features:
- Line items link to specific
discipline_caseposts - Each line item shows match date, match description, card type, and amount
- PDF generation includes a detailed table of discipline cases
- Payment via Mollie payment link (persistent, no expiry)
- QR code generated for the payment link
- Always snapshots the
mollie_default_discipline_account_idaccount when Mollie is active
Membership Invoices
Section titled “Membership Invoices”Created in bulk for an entire season via the bulk invoice creator. Features:
- Line items include the base contribution amount, optional family discount (negative amount), and optional pro-rata discount
- Linked to a season via
_invoice_seasonmeta - Payment via the public payment page (
/betaling/{token}) with plan selection - No PDF attachment — email contains payment link directly
- Supports installment payment plans (see Installments)
- Always snapshots the
mollie_default_membership_account_idaccount when Mollie is active
Manual Invoices
Section titled “Manual Invoices”Manual invoices are created from /financien/facturen/nieuw.
- Default to
mollie_default_manual_account_idwhen Mollie is the active provider - Show a manual account picker only when more than one usable Mollie account exists
- Do not expose account switching for discipline or membership invoices
External manual invoices offer Kies uit adresboek, loading all accessible
person_type: contact records on demand. Search covers contact/company names,
both email addresses and address text; up to twenty matches appear at once.
Selection copies a customer snapshot, leaving the contact unchanged and the
invoice unlinked to a member. The copied fields remain editable.
The snapshot prefers the company name, falling back to the person name. Attention
uses invoice_attention, falling back to the person’s name for company contacts.
The saved invoice_address takes precedence over an address labelled factuur
or the first postal address. With an invoice-specific address, primary and CC
recipients retain their original slots, including an empty primary recipient.
Other contacts use distinct available emails. Missing values clear previous form values.
Opslaan in adresboek saves the current external customer as a reusable
person_type: contact through POST /wp/v2/people. It requires a customer name
and address, and validates both optional email fields. The payload stores the
customer name in company_name, the full address in the native textarea field
invoice_address, attention in invoice_attention, and recipients in email_1
and email_2. It does not split names or postal addresses.
Before creating a contact, the client loads accessible contacts and reuses an
identical customer snapshot after trimming and normalizing newlines. It blocks
repeated clicks while saving and disables automatic mutation retries. This is a
client-side duplicate check, not a server uniqueness constraint. After an uncertain
failure, check Kies uit adresboek before trying again. Saving uses existing
person-create permissions; read-only finance users cannot create contacts.
InvoiceAddressBookContactTest.php and tests/js/invoiceContact.test.mjs cover
permissions, canonical storage and address/recipient round trips.
Explicitly switching invoice kind resets email subject/body to that kind’s configured defaults, including copied invoice overrides. Settings refreshes preserve saved/custom text when the kind remains unchanged.
Linked credit notes
Section titled “Linked credit notes”Finance managers can create a calculated credit draft from a sent, paid or overdue original invoice, or calculate contribution restitution after an eligible injury season. The preview and creation endpoints, source reservations, stored calculations and locked draft workflow are documented in Linked credit notes and injury restitution. These credits use invoice_type: manual and invoice_kind: credit; a refund is handled separately, with an optional Rabobank payment-file export.
Invoice responses expose nullable season. Detail responses also include credit_source_invoice_id, credit_calculation and linked_credits. Financial season history lists assigned and unassigned invoices on the person profile, including former and excluded members. Credit notes receive no payment links, reminders or automatic overdue transition; sending revalidates a calculated draft before PDF/email work.
PDF Generation
Section titled “PDF Generation”Class: Rondo\Finance\InvoicePdfGenerator
Generates PDF documents using the mPDF library. The PDF includes:
- Club branding (logo, name, accent color from
FinanceConfig) - Member details (name, address from
personpost) - Invoice metadata (number, date, due date)
- Only discipline invoices use the four-column discipline table with card and suspension columns; every other type uses description and amount
- Payment instructions and a QR image, when available, only for unpaid normal invoices; credit notes and paid invoices omit them
The due_date is calculated automatically if not set: invoice sent date + configurable payment term days from FinanceConfig.
A draft PDF without sent_date uses _scheduled_send_date when a send date is
planned; otherwise it uses today’s date. A missing due date follows that same
chosen date plus the configured payment term. Rescheduling or cancelling the
schedule changes the preview without marking the invoice as sent. Sent invoices
retain their recorded sent_date and explicit due_date, even if old schedule
metadata remains. InvoicePdfDateTest.php verifies these dates in generated PDFs.
Private Invoice Storage
Section titled “Private Invoice Storage”Rondo\Finance\InvoiceStorage writes new PDFs and payment QR images to
rondo-private/invoices/ beside the WordPress root. The stored field values
keep their relative paths, such as invoices/factuur-{invoice_number}.pdf and
invoices/qr-{invoice_number}.png.
The resolver looks in private storage first and falls back to the legacy uploads
directory for existing files. It accepts only a single file name under
invoices/ and checks that the resolved path stays inside its storage directory.
Use the authenticated download routes.
The deployment guide describes how the web server blocks direct access to
legacy files. Hosting and deployment targets
Email Sending
Section titled “Email Sending”Class: Rondo\Finance\InvoiceEmailSender
Sends HTML emails via wp_mail() with:
- PDF attachment — The generated invoice PDF
- Inline QR code — An embedded image with Content-ID
rondo-invoice-qr - Configurable template — HTML template from
FinanceConfigwith placeholder variables
Invoice emails and reminders pass the QR file to wp_mail() as an embed when
the file exists. The payment link and button also work in clients that hide
inline images. Outbound mail transport
Template Variables
Section titled “Template Variables”| Variable | Description |
|---|---|
{naam} | Full person name |
{voornaam} | First name |
{factuur_nummer} | Invoice number |
{tuchtzaken_lijst} | HTML table of discipline cases |
{totaal_bedrag} | Formatted total (e.g. € 42,50) |
{betaallink} | Payment link as HTML anchor |
{qr_code} | QR code <img> tag |
{organisatie_naam} | Organization name from config |
Email Headers
Section titled “Email Headers”- From: Organization name + contact email from
FinanceConfig - BCC: Optional BCC email from config (omitted in test mode)
- Content-Type:
text/html; charset=UTF-8
Test Mode
Section titled “Test Mode”When override_email is passed in options, the email is sent to that address instead of the member’s email. Both override_email and skip_bcc trigger a [TEST] prefix on the subject line.
Bulk Invoice Creation
Section titled “Bulk Invoice Creation”Class: Rondo\Finance\BulkInvoiceCreator
Creates membership invoices for members in a season who do not already have one, via async WP-Cron batch processing.
The Maak facturen action is only visible when at least one invoice-eligible member does not yet have a membership invoice for the season. Its label shows that pending count. The action asks the financial administrator for confirmation before it starts. The REST request must also include confirmed: true; calls without explicit confirmation are rejected with HTTP 400.
- Start job —
start_job($season)queries publishedpersonposts, removes people who already have a membership invoice for the season, saves the remaining job state to a WordPress option, and schedules the first cron batch - Batch processing — Each batch processes 50 persons via
run_batch(), then schedules the next batch 2 seconds later - Per-person logic —
create_membership_invoice()for each person:- Checks former-member eligibility before reading a cached fee
- Gets the fee via
FeeServices::fee_cache()->get_fee_for_person_cached() - Skips if: no fee data, zero fee, former member not eligible, or invoice already exists (idempotent)
- Creates
rondo_invoicepost withrondo_draftstatus - Generates invoice number with
Cprefix - Builds line items: base fee, optional family discount, optional pro-rata (“instapkorting”) discount
- Generates payment token via
PublicPaymentPage::generate_token()
- Completion — Job status transitions to
donewhen all persons are processed
Job State
Section titled “Job State”Stored in the rondo_bulk_invoice_job WordPress option:
{ "season": "2025-2026", "status": "running", "total": 450, "offset": 100, "created": 85, "skipped": 15, "errors": 0, "started_at": "2025-09-01 12:00:00", "finished_at": null}Only one bulk job can run at a time. Starting a new job while one is running returns a 409 error.
Idempotency
Section titled “Idempotency”Before creating an invoice, the system checks for an existing rondo_invoice with the same person + _invoice_season + invoice_type=membership. If found, the person is skipped.
Former members are eligible only when valid lid_sinds and lid_tot dates prove that their membership interval overlaps the requested season. A missing or invalid end date is deliberately fail-closed: bulk and single-member automatic invoice creation skip that person.
REST API
Section titled “REST API”All endpoints are under rondo/v1/invoices. Reads (list, single, PDF, QR, invoiced-cases) require financieel_read; every write requires financieel.
The separate payment statistics page requests GET /invoices/statistics. This read-only endpoint accepts an optional invoice_type filter (membership, discipline, or manual) and returns the amount and number of recorded payments in rolling 7- and 30-day windows, plus the average number of calendar days between sent_date and full payment for invoices paid in the last 30 days. It also returns zero-filled daily income for the last 30 calendar days and monthly income for the last 12 calendar months. Mollie installments count as separate receipts including their administration fee; a manual paid mark counts only the remaining invoice principal so earlier installments are not counted twice. Credit invoices and invoices without a reliable payment timestamp are excluded from income and lead-time calculations. The response also counts unique people on current-season membership invoices with a 3- or 8-installment plan; draft and cancelled invoices are excluded. The current-season distributions follow the optional invoice type filter: invoice_payment_status separates fully paid, installment, and open invoices, while invoice_amount_status compares collected principal with total principal without installment administration fees. Membership invoices use their explicit sports season; other invoice types use the sports season containing their sent date. The legacy membership-only distribution fields remain available for existing clients.
Key Endpoints
Section titled “Key Endpoints”| Method | Endpoint | Description |
|---|---|---|
| GET | /invoices | List invoices (filterable by status, type, person) |
| GET | /invoices/statistics | Filterable payment totals, lead time, and daily/monthly income series |
| POST | /invoices | Create a new discipline invoice |
| POST | /invoices/credits/preview | Validate and preview a linked or injury credit without creating a draft |
| POST | /invoices/credits | Create a calculated credit draft with request replay protection |
| GET | /invoices/{id} | Get invoice details |
| DELETE | /invoices/{id} | Delete a draft invoice |
| POST | /invoices/{id}/send | Send invoice (generates PDF, creates payment link, sends email, transitions to rondo_sent) |
| POST | /invoices/{id}/mark-paid | Manually mark as paid |
| POST | /invoices/{id}/preview-email | Send test email to override address |
| POST | /invoices/bulk | Start bulk membership invoice creation |
| GET | /invoices/bulk/status | Get bulk job progress |
Send Flow
Section titled “Send Flow”The send endpoint orchestrates the full sending pipeline:
- Validate invoice is in
rondo_draftstatus - Revalidate stored credit calculations where present
- Prepare payment link and QR before PDF generation: credits clear payment/QR data, membership invoices retain their public payment URL, and other invoices use
MolliePaymentorRabobankPayment - Generate PDF via
InvoicePdfGenerator - Send email via
InvoiceEmailSender - Transition post status to
rondo_sent - Set
sent_dateand calculatedue_date
Related Documentation
Section titled “Related Documentation”- Payments — Mollie and Rabobank payment integration
- Installments — Installment payment plans for membership invoices
- Membership Fees — Fee calculation and season configuration