Appearance
Invoicing
TiruPay integrates with external invoicing providers to automatically create invoices, credit notes, and dunning notices. The invoicing system is provider-agnostic - you configure which provider a service uses, and TiruPay handles the rest.
How Invoicing Works
When an order is finalized, TiruPay automatically:
- Syncs the customer as a contact in the invoicing provider.
- Creates an invoice from the order positions, prices, and tax data.
- Stores the external invoice ID and the invoice number on the order.
- Starts the payment, with the invoice number as payment reference.
plain
Finalize Order
↓
Sync customer → Invoicing Provider (create/update contact)
↓
Create invoice → Invoicing Provider (create invoice)
↓
Store ext_invoice_id and invoice_number on order
↓
Start payment (reference: "Invoice <invoice_number>")The same applies to subscription renewals, upgrades and pay-as-you-go billing charged via a mandate: the invoice is created right before the charge.
INFO
Invoices are created when the order transitions to PENDING - before payment is completed. This means the invoice exists in the external system regardless of whether the customer pays immediately.
Payment Reference
The customer sees Invoice <invoice_number> (in the customer's language, e.g. Rechnung RE-2026-00001) as reference of the payment, e.g. on a SEPA direct debit or bank statement. If no invoicing provider is configured, or the invoice could not be created, the reference names the order number instead. Orders with capture_mode: manual are invoiced only when the capture is confirmed, after the payment was authorized, so their payment reference always names the order number.
Invoicing Providers
Each service can be configured with an invoicing provider. If no provider is configured, TiruPay uses a no-op provider that does nothing.
| Provider | Description |
|---|---|
pdf | Built-in PDF provider - generates invoicing documents directly within TiruPay, without any external service. See PDF Provider below. |
sevdesk | SevDesk - German cloud accounting software. Full support for invoices, credit notes, dunning, and PDF generation. |
noop | No external invoicing. Invoice operations succeed silently without creating anything. Used for testing or services that handle invoicing externally. |
Service Configuration
To enable invoicing for a service, set the following fields on the service:
| Field | Type | Required | Description |
|---|---|---|---|
invoicing_provider_type | enum | no | pdf, sevdesk, or null (no provider) |
invoicing_api_token | string | conditional | API token for the invoicing provider. Required for sevdesk. Not used for pdf. |
ext_invoicing_id | string | conditional | External system ID (e.g. SevDesk organization ID). Not required for pdf. |
WARNING
Choose the provider when creating the service: the dashboard does not offer to change invoicing_provider_type afterwards, only the provider's credentials and IDs. Existing documents stay with the old provider - the stored ext_invoice_ids and contact IDs belong to it. After a switch from pdf to sevdesk, for example, a cancellation looks for the original invoice in SevDesk, where it does not exist, so cancelling, crediting or dunning invoices created before the switch fails.
Changing invoicing_provider_type via the API is still possible. Only do it if you know exactly which documents are affected and can live with these consequences.
The service never returns invoicing_api_token, only has_invoicing_api_token. Updating a service without invoicing_api_token keeps the stored token.
SevDesk-Specific Configuration
| Field | Description |
|---|---|
sev_desk_customer_category_field_id | Customer category field ID in SevDesk |
sev_desk_contact_person_id | SevUser ID used as contact person on invoices |
sev_desk_check_account_id | CheckAccount ID for booking payments as paid |
sev_desk_letterpaper_id | Optional letterpaper for every document TiruPay creates in SevDesk - invoices, credit notes, cancellations, dunning notices and offers. Empty uses the SevDesk default letterpaper. |
SevDesk documents
- Invoices appear in SevDesk as open. SevDesk does not send them - the invoice email comes from TiruPay.
- Positions show gross prices, so the document total always matches the amount the customer pays, to the cent.
- If the configured letterpaper cannot be applied, the document is still created and keeps the SevDesk default letterpaper.
PDF Provider Configuration
The seller name shown on all documents is taken from the service's name field.
| Field | Description |
|---|---|
invoicing_street | Seller street address |
invoicing_postal_code | Seller postal code |
invoicing_city | Seller city |
invoicing_country_code | Seller country (ISO 3166-1 alpha-2, e.g. DE) |
invoicing_email | Seller email shown on documents |
invoicing_phone | Seller phone (optional) |
invoicing_vat_id | Seller VAT ID (at least one of VAT ID or tax number required) |
invoicing_tax_id | Seller tax number (Steuernummer) |
invoicing_iban | Bank IBAN shown on invoices and dunning notices |
invoicing_bic | Bank BIC (optional) |
invoicing_dunning_text | Notice text shown on automatically generated dunning notices. Required if dunning is used with this provider. |
PDF Provider
The PDF provider generates all invoicing documents entirely within TiruPay - no external accounting service or API key required. Documents are generated as PDF/A-3b files and comply with the Factur-X / ZUGFeRD EN 16931 standard for electronic invoices (E-Rechnung).
Supported Documents
| Document | Description |
|---|---|
| Invoice (Rechnung) | Standard invoice with embedded machine-readable XML. Suitable as a legally valid E-Rechnung. |
| Credit note (Gutschrift) | Full credit note referencing the original invoice, with embedded XML. |
| Cancellation (Rechnungskorrektur) | Cancels an existing invoice with a corrective document, with embedded XML. |
| Offer (Angebot) | Non-binding quote document. No embedded XML - not an E-Rechnung. |
| Dunning notice (Mahnung) | Payment reminder referencing an open invoice. No embedded XML. |
Document Numbering
TiruPay maintains a per-service sequence for each document type (invoices, credit notes, cancellations, offers, dunning notices). Numbers are generated automatically using the service's configured order_number_template, prefixed by document type:
| Document type | Prefix | Example |
|---|---|---|
| Invoice (Rechnung) | RE | RE-2024-00001 |
| Credit note (Gutschrift) | GS | GS-2024-00001 |
| Cancellation (Rechnungskorrektur) | SR | SR-2024-00001 |
| Offer (Angebot) | AG | AG-2024-00001 |
| Dunning notice (Mahnung) | MA | MA-2024-00001 |
Each sequence is independent per service - sequences from different services never overlap. The number format follows the service's configured order_number_template (see Order Numbers).
Dunning Notices
Dunning notices are generated automatically as part of a service's dunning escalation. The notice text comes from the service's invoicing_dunning_text - if it's not set, dunning fails for that order and logs an error. Unlike SevDesk, the PDF provider can show every dunning fee ever charged on the order as its own line item on the notice, not just a single total - see Provider Support.
Limitations
- The PDF provider does not sync contacts to an external system - contact data is taken directly from the order at document generation time.
Invoice Types
TiruPay supports the following invoicing documents:
| Type | Description |
|---|---|
invoice | Standard invoice (Rechnung) - created when an order is finalized |
credit_note | Credit note (Gutschrift) - references an original invoice. Used for full or partial refunds. |
cancellation | Cancellation invoice (Rechnungskorrektur) - voids an existing invoice with a corrective document. |
dunning | Dunning notice (Mahnung) - payment reminder for overdue invoices. |
offer | Non-binding offer (Angebot) - generated from a draft order, not part of the invoice history. |
Invoice Lifecycle
Creation
When an order is finalized:
- The customer is synced as a contact in the invoicing provider. If the customer has no
ext_invoicing_idyet, the provider creates a new contact and stores the ID. - An invoice is built from the order's positions, including article names, quantities, unit prices, discounts, and tax rates.
- The provider creates the invoice and returns an external invoice ID.
- The ID is stored on the order as
ext_invoice_id(the currently active invoice) and appended toext_invoice_ids(the history). The invoice number is stored asinvoice_number(not set fornoop).
Non-Blocking
Invoice creation errors are caught and logged - they do not prevent the order from being finalized. If the invoice fails to create, the order continues with payment processing.
Credit Notes
When an order is refunded, TiruPay creates a credit note referencing the original invoice.
- Full credit note: All positions, amounts, and contact data are copied from the original invoice. Used for full refunds where no individual position breakdown is needed.
- Line-item credit note: One position per refunded item, with exact net prices and tax rates. Used for the pro-rata refund of a terminated subscription, where the refunded amount is a fraction of each original position. Both the PDF provider and SevDesk support this.
- Partial credit note: A single aggregated position for a given gross amount. The tax rate is back-calculated from the original invoice. Used for partial position refunds.
If a refund was credited to the customer's Credit Balance, the credit note includes an informational note showing the credited amount. This note is not part of the invoice totals.
The credit note is booked as paid in the invoicing provider immediately after creation if no payment processor refund is involved (i.e. the full amount goes to the Credit Balance).
The credit note ID is appended to ext_invoice_ids with type credit_note.
Pro-Rata Refunds on the Next Invoice
An upgrade, or a termination that deducts its refund from another order, issues no credit note. The unused remainder of the replaced order is shown on the invoice of the new order as negative positions instead, one per tax rate of the replaced order. The deduction never exceeds the invoice total or the Credit Balance actually used for the order; any rest stays on the Credit Balance.
Credit Balance on Invoices
Apart from such a deduction, the invoice shows the full order amount, regardless of how the customer paid. If Credit Balance was used beyond the deduction, a footer states the amount paid via Credit Balance and the remaining amount due.
Booking
Both invoices and credit notes need to be booked as paid in the invoicing provider once the actual payment or refund has been processed. This marks them as settled in the external accounting system.
Dunning
For revoked orders whose service has an active dunning policy, TiruPay creates dunning notices:
- A dunning notice is created at the provider, referencing the active invoice.
- The dunning ID is appended to
ext_invoice_idswith typedunning. - The order status transitions to
DUNNING. next_dunning_dateis set for when the next tier should fire - from the provider's own reminder deadline if it returns one (SevDesk), or calculated locally otherwise (PDF, no-op).
See Dunning for the full escalation model.
Invoice History
Every order maintains a complete history of all invoicing activity in the ext_invoice_ids field:
json
[
{ "id": "inv_123", "type": "invoice" },
{ "id": "cn_456", "type": "credit_note" },
{ "id": "dun_789", "type": "dunning" },
{ "id": "can_012", "type": "cancellation" }
]The ext_invoice_id field always points to the currently active invoice, invoice_number holds its number. When an invoice is cancelled, both fields are cleared.
PDFs
You can retrieve the PDF for any entry in the order's invoice history. The PDF endpoint automatically determines the correct provider method based on the type field in ext_invoice_ids - credit note PDFs are fetched separately from invoice PDFs.
Offer PDF
For orders still in DRAFT status, you can generate a non-binding offer (Angebot) PDF. TiruPay creates the offer document in the invoicing provider and returns the PDF — the order remains in DRAFT.
Contact Sync
When TiruPay syncs a customer with the invoicing provider, the following data is sent:
- Personal: First name, last name, email, phone
- Address: Street, city, postal code, country
- Company: Company name, VAT ID, tax exemption status (for company customers)
The sync is idempotent - if the contact already exists, it's updated only if there are changes. The external contact ID is stored on the customer as ext_invoicing_id.
Discount Handling
Discounts from coupons are represented as separate negative line items on the invoice (e.g. "Discount Pro Plan" with a negative amount). This avoids rounding errors compared to applying percentage discounts on individual positions.
Good to know
Invoice Numbers
For external providers (e.g. SevDesk), invoice numbers are generated by the provider. For the built-in PDF provider, TiruPay maintains a per-service number sequence for each document type and generates numbers automatically.
One Invoice Per Finalization
An invoice is created each time an order is finalized. If a payment fails and the customer retries, a new invoice is created for the new attempt. Mandate charges (renewals, upgrades, pay-as-you-go) that fail keep their invoice, and every retry charges the same invoice.
Customer Contact Reuse
Once a customer is synced with the invoicing provider (via ext_invoicing_id), subsequent orders reuse the same contact - it's updated if the customer's data has changed.
Dunning Requires a Policy
Dunning runs daily, but only for services with an active dunning policy - a service with none configured is never automatically escalated. When it does run, the order transitions to DUNNING status.
Invoice operations follow the order's access control - if a user can access the order, they can view its invoices.
Relationships
- Orders - Invoices are created for orders. Each order tracks its invoice history.
- Customers - Customers are synced as contacts in the invoicing provider.
- Services - Invoicing provider configuration is set per service.
- Taxation - Tax rates and values from order positions are included in invoices.
- Coupons - Coupon discounts appear as separate negative positions on invoices.
- Dunning - Dunning notices are created through the invoicing provider; only PDF can show itemized fee lines.