> ## Documentation Index > Fetch the complete documentation index at: https://docs.paywise.de/llms.txt > Use this file to discover all available pages before exploring further. # Invoice groups — implementation plan > Planned joint reminders for separate monthly invoices, with individual PDFs, calculated balances and invoice-level settlement. **Status: 30 September 2026 — implemented and under review, not yet released.** This page describes the planned invoice-group feature so you can prepare your integration. It is not yet available for sandbox testing or production use. The group endpoints and document deletion described here are not included in the currently published preview OpenAPI schema. Final details and sandbox access will be confirmed separately after review and integration testing. ## Several monthly invoices, one Mahnlauf The planned feature groups separate monthly invoices for one debtor into a single reminder sequence. Each monthly invoice keeps its own invoice number, invoice date, due date, amount and PDF. paywise calculates the combined amount and outstanding balance. A separate **Hauptrechnung is not required**. The group reference identifies the shared Mahnlauf; it does not create an additional invoice or receivable. For example, ten monthly invoices can be submitted together with their ten PDFs and followed up in one reminder sequence. ## Data to prepare For each group, provide a unique group reference, an existing debtor ID and one currency. All member invoices belong to the same company, debtor and environment. Grouping is explicit; invoices are not combined automatically just because they have the same debtor. For every monthly invoice, prepare: | Field | Planned requirement | | - | - | | `invoice_number` | The invoice's own unique number. | | `document_date` | The invoice date, no later than its due date. | | `due_date` | An explicit due date for this invoice. | | `amount` | A positive invoice amount in the group's currency. | | PDF | This invoice's own document, uploaded after group creation. | Send the structured fields explicitly. The planned API does not extract the invoice number, dates or amount from uploaded PDFs. Missing due dates must be resolved before submission. paywise calculates the group total from the individual amounts; the request does not supply a separate total. ## Planned submission flow 1. Create the group and all its monthly invoices in one request. The response provides the group ID and each invoice ID. The group starts **held**. 2. Upload one PDF to each member invoice through its invoice document endpoint. 3. Wait until every outstanding member's document is `ready`. Correct invoice fields or replace/delete documents while the group is still held. 4. Release the group once. This starts one shared Mahnlauf, subject to the company's configured workflow and activation rules. The planned creation endpoint is `POST /mahnservice/v1/invoice-groups/`. This illustrative request is for integration planning; it cannot yet be sent to a released group endpoint: ```json theme={null} { "reference": "MONTHLY-GROUP-2026-09-001", "debtor": "11111111-1111-4111-8111-111111111111", "currency": "EUR", "invoices": [ { "invoice_number": "MONTH-2026-08-001", "document_date": "2026-08-01", "due_date": "2026-08-15", "amount": "58.31" }, { "invoice_number": "MONTH-2026-09-001", "document_date": "2026-09-01", "due_date": "2026-09-15", "amount": "58.31" } ] } ``` The calculated group amount in this example is **EUR 116.62**. Each PDF is uploaded separately to `/mahnservice/v1/invoices/{invoice_id}/documents/`. Release is planned through `POST /mahnservice/v1/invoice-groups/{group_id}/release/`, with no request body. Members are not released individually. Keep the returned IDs and use a stable group reference for retries. Under the planned contract, repeating a reference returns the existing group with `200` only when its debtor, currency and complete member set match the currently stored data. Each member's invoice number, amount, document date and due date must match; member order in the request does not matter. Different data returns `409 group_reference_conflict` without changing the group or its invoices. Correct held members through their invoice IDs. Later creation retries compare against those corrected values; repeating the old values then returns a conflict. Cancelled, written-off or archived group references continue to return their terminal-state conflicts (`invoice_cancelled`, `invoice_written_off` or `invoice_archived`). An invoice already submitted separately cannot also be added to a new group. ## Reminder timing and outstanding balance At release, the first reminder is scheduled from the **latest due date among the outstanding member invoices**, plus the first-step delay configured in the company's Mahnlauf. Existing scheduling, activation and pause rules still apply; release does not mean that a reminder is sent immediately. Payments are reported against the individual invoice they settle. paywise calculates the next group reminder from the remaining member balances. For example, a EUR 10.00 payment against one of the invoices above leaves **EUR 106.62** outstanding for the group. The API does not automatically allocate an unidentified group payment or move an overpayment to another member invoice. Paid, cancelled and written-off invoices contribute zero to subsequent reminders. When no outstanding member balance remains, the group stops. ## Corrections and documents in the first version Correct member invoice fields and replace or delete their PDFs **before group release**. After release, invoice data, membership and PDFs remain fixed for this first version. Payment reporting and eligible cancellation/write-off remain settlement actions before Inkasso handover; they do not delete the invoice history or edit its PDF. Document deletion while held is planned through `DELETE /mahnservice/v1/invoices/{invoice_id}/documents/{document_id}/`. It is not part of the currently published preview schema. An outstanding member whose PDF was removed needs a ready replacement before group release. Repeating an upload replaces that invoice's PDF; it does not add another attachment to the same invoice. The proposed initial limits are **50 invoices per group**, **10 MiB and 100 pages per PDF**, and **20 MiB of original PDFs per group**. These are implementation limits under review, not a required number of invoices. Check a representative set of your files against them when preparing the integration. ## Email reminders, letters and Inkasso Email and letter reminders show an itemized list of outstanding invoices and the combined balance. Wording follows the reminder stage, including the final Inkasso warning when configured. Each invoice keeps its own due date in the breakdown; the summary labels the latest due date without suggesting that all invoices have been overdue for the same number of days. The existing Mahnlauf setting for attaching original invoices controls whether email reminders include the outstanding members' PDFs. Letters contain the invoice breakdown; original PDFs are not automatically printed with the letter. In the portal, either the group reference or a member's invoice number will find the shared Mahnlauf. Inkasso handover preserves the outstanding monthly invoices as separate claims in one order, including their invoice numbers, dates, amounts, individual PDFs and assigned payments. Shared reminder fees are transferred once. The group does not create an additional aggregate claim. After handover, the Inkasso case owns settlement. Reporting a payment through the Mahnservice API does not update that collection case, and Mahnservice cancellation/write-off is refused. Coordinate subsequent collection changes with paywise. ## Next steps for your integration You can prepare the invoice data mapping, group references, per-invoice payment allocation and representative PDFs now. Code review and integration testing come next. paywise will then confirm sandbox access and provide the updated machine-readable contract for end-to-end testing. No release date is committed by this plan. See the [developer preview introduction](/api-docs/mahnservice-api/introduction) for access status and the [current lifecycle rules](/api-docs/mahnservice-api/lifecycle) for the already published single-invoice preview.