Skip to content

Invoicing System

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).

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.

Invoices use the rondo_invoice custom post type with four custom post statuses:

StatusSlugDescription
Draftrondo_draftNewly created, not yet sent
Sentrondo_sentSent to member via email
Paidrondo_paidPayment confirmed (via Mollie webhook or manual)
Overduerondo_overduePast due date, not yet paid

Each invoice stores the following fields:

  • invoice_number — Unique formatted number (e.g. F2025-042 or C2025-001)
  • person — Relationship to the person post type
  • status — ACF status mirror (draft, sent, paid, overdue)
  • invoice_type — Either discipline or membership
  • total_amount — Decimal total
  • line_items — Repeater field with sub-fields:
    • discipline_case — Optional relationship to a discipline case
    • description — Text description (used for membership line items)
    • amount — Decimal amount (negative for discounts)
  • payment_link — Mollie checkout URL or public payment page URL
  • pdf_path — Relative invoice PDF path, read-only in the field API
  • qr_code_path — Relative invoice QR image path, read-only in the field API
  • sent_date — Date invoice was sent (Ymd format)
  • due_date — Payment due date (Ymd format)

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.

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.

Class: Rondo\Finance\InvoiceNumbering

Invoice numbers follow the format {PREFIX}{YEAR}-{SEQ} where:

  • Discipline invoices: Prefix F (e.g. F2025-001)
  • Membership invoices: Prefix C for “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.

Created manually via the REST API when a member receives fines from discipline cases (yellow/red cards). Features:

  • Line items link to specific discipline_case posts
  • 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_id account when Mollie is active

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_season meta
  • 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_id account when Mollie is active

Manual invoices are created from /financien/facturen/nieuw.

  • Default to mollie_default_manual_account_id when 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.

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.

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 person post)
  • 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.

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

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 FinanceConfig with 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

VariableDescription
{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
  • From: Organization name + contact email from FinanceConfig
  • BCC: Optional BCC email from config (omitted in test mode)
  • Content-Type: text/html; charset=UTF-8

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.

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.

  1. Start job — start_job($season) queries published person posts, 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
  2. Batch processing — Each batch processes 50 persons via run_batch(), then schedules the next batch 2 seconds later
  3. 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_invoice post with rondo_draft status
    • Generates invoice number with C prefix
    • Builds line items: base fee, optional family discount, optional pro-rata (“instapkorting”) discount
    • Generates payment token via PublicPaymentPage::generate_token()
  4. Completion — Job status transitions to done when all persons are processed

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.

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.

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.

MethodEndpointDescription
GET/invoicesList invoices (filterable by status, type, person)
GET/invoices/statisticsFilterable payment totals, lead time, and daily/monthly income series
POST/invoicesCreate a new discipline invoice
POST/invoices/credits/previewValidate and preview a linked or injury credit without creating a draft
POST/invoices/creditsCreate a calculated credit draft with request replay protection
GET/invoices/{id}Get invoice details
DELETE/invoices/{id}Delete a draft invoice
POST/invoices/{id}/sendSend invoice (generates PDF, creates payment link, sends email, transitions to rondo_sent)
POST/invoices/{id}/mark-paidManually mark as paid
POST/invoices/{id}/preview-emailSend test email to override address
POST/invoices/bulkStart bulk membership invoice creation
GET/invoices/bulk/statusGet bulk job progress

The send endpoint orchestrates the full sending pipeline:

  1. Validate invoice is in rondo_draft status
  2. Revalidate stored credit calculations where present
  3. Prepare payment link and QR before PDF generation: credits clear payment/QR data, membership invoices retain their public payment URL, and other invoices use MolliePayment or RabobankPayment
  4. Generate PDF via InvoicePdfGenerator
  5. Send email via InvoiceEmailSender
  6. Transition post status to rondo_sent
  7. Set sent_date and calculate due_date
  • Payments — Mollie and Rabobank payment integration
  • Installments — Installment payment plans for membership invoices
  • Membership Fees — Fee calculation and season configuration