Übersicht
Autorisierte Abrechnungsadministratoren können unter Einstellungen -> Abrechnung -> Rechnungen (/settings/billing/invoices) die vollständige Abrechnungshistorie (GET /api/v1/billing/history), Einzelpostenaufstellungen (invoice line item type) und Zahlungsabwicklungsstatus einsehen. Unterstützt durch den Billing API (/api/v1/billing/invoices* sowie GET /api/v1/billing/tax-profile/datev-export) erstellt Passinstance USt.-konforme PDF-Steuerrechnungen für jede Abonnementverlängerung, unterjährige anteilige Anpassung (Proration) und modulare Add-on-Gebühr und ermöglicht die sofortige Zahlungsausführung oder Stornierung offener Rechnungen.
Rechnungserstellung & Lebenszyklus der Zahlungsabwicklung
Wichtig: Unternehmensbezogene Abrechnungsmetadaten (
companyName,address,taxIdundvatNumberüberPUT /api/v1/billing/settingsundPUT /api/v1/billing/tax-profile) werden bei der Finalisierung jeder Rechnung als unveränderlicher Snapshot festgeschrieben. Halten Sie Ihre Steuerdaten in den Unternehmenseinstellungen vor Ihrem Verlängerungsdatum auf dem neuesten Stand.
Rechnungsstatus (invoice status), Lebenszyklus & Positionsarten
Rechnungen verfolgen sowohl einen administrativen Lebenszyklus (invoice lifecycle state: DRAFT | OPEN | CLOSED | VOID) als auch einen Zahlungsabwicklungsstatus (invoice status), während Einzelpositionen invoice line item type (BASE_SUBSCRIPTION | ADD_ON | ACTIVE_PASSES_INCLUDED | ACTIVE_PASSES_OVERAGE | USAGE_EMAIL | USAGE_SMS | CREDIT_NOTE | ADJUSTMENT | TAX) verwenden:
| invoice status | Buchhalterische Bedeutung | Empfohlene Maßnahme des Betreibers |
|---|---|---|
PAID | Die Zahlung wurde erfolgreich über die Standard-Zahlungsmethode des Workspaces eingezogen und verbucht. | Laden Sie den offiziellen PDF-Steuerbeleg über /download für Ihre Buchhaltung herunter. |
PENDING / PARTIALLY_PAID | Die Rechnung wurde finalisiert (OPEN) und wartet auf den Zahlungseinzug oder den Ausgleich eines Restbetrags. | Überprüfen Sie Ihr Standard-Zahlungsmittel unter Zahlungsmethoden und lösen Sie POST /api/v1/billing/invoices/:id/pay aus. |
OVERDUE | Die automatische Zahlung ist nach dem ersten Abbuchungszeitfenster fehlgeschlagen (z. B. abgelaufene Karte oder erforderliche 3DS-Freigabe). | Aktualisieren Sie Karte bzw. Mandat unter /settings/billing/payment-method und wiederholen Sie die Zahlung über POST /api/v1/billing/invoices/:id/pay. |
CANCELLED / VOID | Die Rechnung wurde vor dem Einzug storniert (POST /api/v1/billing/invoices/:id/cancel) oder für ungültig erklärt. | Es ist keine Zahlung fällig; bewahren Sie den Beleg bei Bedarf für Ihre Revisionsunterlagen auf. |
API-Referenz zur Rechnungsverwaltung (Billing API)
| Endpunkt | HTTP-Verb | Beschreibung |
|---|---|---|
/api/v1/billing/invoices | GET | Listet paginierte Workspace-Rechnungen auf (?page=1&limit=20). |
/api/v1/billing/invoices/:id | GET | Ruft eine detaillierte Rechnungsaufschlüsselung ab, einschließlich Einzelpositionen (invoice line item type), Steuersätzen, USt.-Hinweisen und Zahlungsversuchen. |
/api/v1/billing/invoices/:id/download | GET | Streamt die offizielle, nach Einzelposten aufgeschlüsselte Steuerrechnung als application/pdf-Anhang. |
/api/v1/billing/invoices/:id/pay | POST | Begleicht eine ausstehende oder überfällige Rechnung bzw. wiederholt den Einzug über die aktive Zahlungsmethode des Workspaces. |
/api/v1/billing/invoices/:id/cancel | POST | Storniert eine unbezahlte offene Rechnung. |
/api/v1/billing/history | GET | Gibt den chronologischen Verlauf aller Abrechnungs- und Zahlungsereignisse des Workspaces zurück. |
1. Detaillierte Rechnungspositionen & USt. prüfen (GET /api/v1/billing/invoices/:id)
GET /api/v1/billing/invoices/inv_01933220-5a11-7e00-9c44-887766554433 HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Antwort-Payload (200 OK)
{
"id": "inv_01933220-5a11-7e00-9c44-887766554433",
"invoiceNumber": "PI-2026-004891",
"status": "PAID",
"lifecycle": "CLOSED",
"currency": "EUR",
"issuedAt": "2026-11-16T09:00:00.000Z",
"paidAt": "2026-11-16T09:00:04.000Z",
"customerDetails": {
"companyName": "Phenix Hospitality GmbH",
"vatNumber": "DE301928374",
"address": "Friedrichstrasse 114A, 10117 Berlin, DE"
},
"lineItems": [
{
"kind": "BASE_SUBSCRIPTION",
"description": "Growth Plan (2,000 Active Passes) — Monthly",
"quantity": 1,
"unitAmountCents": 12000,
"amountCents": 12000
},
{
"kind": "ADD_ON",
"description": "Custom Vanity Domain & Branded Email Add-On",
"quantity": 1,
"unitAmountCents": 2900,
"amountCents": 2900
}
],
"subtotalCents": 14900,
"taxRatePercent": 19.0,
"taxCents": 2831,
"totalCents": 17731
}
2. PDF-Steuerrechnungen streamen (GET /api/v1/billing/invoices/:id/download)
GET /api/v1/billing/invoices/inv_01933220-5a11-7e00-9c44-887766554433/download HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice-PI-2026-004891.pdf"
3. Zahlung für eine offene/überfällige Rechnung erneut ausführen (POST /api/v1/billing/invoices/:id/pay)
Aktualisieren Sie Ihr Standard-Zahlungsmittel unter Einstellungen -> Abrechnung -> Zahlungsmethode (/settings/billing/payment-method) und lösen Sie anschließend den Einzug aus (kein Request-Body erforderlich):
POST /api/v1/billing/invoices/inv_01933299-1b22-7c00-8d11-223344556677/pay HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"invoiceId": "inv_01933299-1b22-7c00-8d11-223344556677",
"status": "PAID",
"paidAt": "2026-11-16T10:36:45.000Z",
"amountPaidCents": 17731
}
Weiterführende Dokumentation
-
Konfigurieren Sie Unternehmenssteuerdaten und USt-IdNrn. unter Unternehmenseinstellungen.
-
Fügen Sie Kreditkarten, PayPal oder Mobile Money unter Zahlungsmethoden hinzu oder aktualisieren Sie diese.
-
Exportieren Sie Workspace-Daten und Compliance-Protokolle unter Datenexporte & Berichte.
