Invoice groups — implementation plan - paywise Knowledge Center

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

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.
Upload one PDF to each member invoice through its invoice document endpoint.
Wait until every outstanding member’s document is ready. Correct invoice fields or replace/delete documents while the group is still held.
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:

{
  "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. An eligible repeated group reference returns the existing group; it does not apply changed invoice data. Correct held members through their invoice IDs. 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. 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. 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 for access status and the current lifecycle rules for the already published single-invoice preview.

Automation platforms

Case Management API

Partner API

Mahnservice API (developer preview)

Invoice groups — implementation plan

Several monthly invoices, one Mahnlauf

Data to prepare

Planned submission flow

Reminder timing and outstanding balance

Corrections and documents in the first version

Email reminders, letters and Inkasso

Next steps for your integration

​Several monthly invoices, one Mahnlauf

​Data to prepare

​Planned submission flow

​Reminder timing and outstanding balance

​Corrections and documents in the first version

​Email reminders, letters and Inkasso

​Next steps for your integration

Several monthly invoices, one Mahnlauf

Data to prepare

Planned submission flow

Reminder timing and outstanding balance

Corrections and documents in the first version

Email reminders, letters and Inkasso

Next steps for your integration