Overzicht
Geautoriseerde facturatiebeheerders kunnen de volledige historische facturatielijst (GET /api/v1/billing/history), factuurregels (invoice line item type) en betaalstatussen bekijken onder Instellingen -> Facturatie -> Facturen (/settings/billing/invoices). Ondersteund door Billing API (/api/v1/billing/invoices* en GET /api/v1/billing/tax-profile/datev-export) genereert Passinstance btw-conforme PDF-belastingfacturen voor elke abonnementsverlenging, pro-rata tussentijdse aanpassing en modulaire add-on, en maakt directe betaling of annulering van openstaande facturen mogelijk.
Levenscyclus van factuurgeneratie & afrekening
Belangrijk: Zakelijke factuurgegevens (
companyName,address,taxIdenvatNumberviaPUT /api/v1/billing/settingsenPUT /api/v1/billing/tax-profile) worden op elke factuur vastgelegd zodra deze wordt afgerond. Houd uw belastinggegevens actueel in Bedrijfsinstellingen vóór uw verlengingsdatum.
Factuurstatus (invoice status), levenscyclus & regelsoorten
Facturen houden zowel een administratieve levenscyclus bij (invoice lifecycle state: DRAFT | OPEN | CLOSED | VOID) als een betalingsstatus (invoice status), terwijl afzonderlijke regels invoice line item type gebruiken (BASE_SUBSCRIPTION | ADD_ON | ACTIVE_PASSES_INCLUDED | ACTIVE_PASSES_OVERAGE | USAGE_EMAIL | USAGE_SMS | CREDIT_NOTE | ADJUSTMENT | TAX):
| invoice status | Boekhoudkundige betekenis | Aanbevolen actie |
|---|---|---|
PAID | Betaling is geslaagd en afgerekend via de standaard betaalmethode van de werkruimte. | Download het officiële PDF-belastingbewijs via /download voor uw administratie. |
PENDING / PARTIALLY_PAID | De factuur is definitief (OPEN) en wacht op incasso of gedeeltelijke voldoening. | Controleer uw standaard betaalinstrument in Betaalmethoden en voer POST /api/v1/billing/invoices/:id/pay uit. |
OVERDUE | Automatische betaling is mislukt na het eerste incassovenster (bijv. verlopen kaart of vereiste 3DS-verificatie). | Werk uw kaart/mandaat bij in /settings/billing/payment-method en probeer opnieuw via POST /api/v1/billing/invoices/:id/pay. |
CANCELLED / VOID | Factuur werd geannuleerd (POST /api/v1/billing/invoices/:id/cancel) of ongeldig verklaard vóór incasso. | Geen betaling verschuldigd; bewaar het document desgewenst voor volledige auditopbouw. |
API-referentie factuurbeheer (Billing API)
| Endpoint | HTTP-methode | Beschrijving |
|---|---|---|
/api/v1/billing/invoices | GET | Geeft gepagineerde facturen van de werkruimte weer (?page=1&limit=20). |
/api/v1/billing/invoices/:id | GET | Haalt gedetailleerde factuurgegevens op inclusief factuurregels (invoice line item type), btw-tarieven, btw-notities en betaalpogingen. |
/api/v1/billing/invoices/:id/download | GET | Streamt de officiële gespecificeerde btw-factuur als application/pdf-bijlage. |
/api/v1/billing/invoices/:id/pay | POST | Betaalt of probeert opnieuw een openstaande/achterstallige factuur te innen met de actieve betaalmethode van de werkruimte. |
/api/v1/billing/invoices/:id/cancel | POST | Annuleert een onbetaalde open factuur. |
/api/v1/billing/history | GET | Retourneert chronologische facturatie- en betaalgebeurtenissen van de werkruimte. |
1. Gedetailleerde factuurregels & btw bekijken (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>
Antwoordpayload (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-belastingfacturen 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. Betaling opnieuw starten op een openstaande factuur (POST /api/v1/billing/invoices/:id/pay)
Werk uw standaard betaalinstrument bij onder Instellingen -> Facturatie -> Betaalmethode (/settings/billing/payment-method) en start daarna de incasso (geen JSON-body vereist):
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
}
Gerelateerde documentatie
-
Configureer fiscale bedrijfsgegevens en btw-nummers in Bedrijfsinstellingen.
-
Voeg creditcards, PayPal of Mobile Money toe in Betaalmethoden.
-
Exporteer werkruimtegegevens en nalevingslogboeken in Gegevensexports & rapportage.
