Overview
Authorized billing administrators can inspect complete historical billing records (GET /api/v1/billing/history), line-item breakdowns (invoice line item type), and payment settlement statuses under Settings -> Billing -> Invoices (/settings/billing/invoices). Powered by Billing API (/api/v1/billing/invoices* and GET /api/v1/billing/tax-profile/datev-export), Passinstance generates VAT-compliant PDF tax invoices for every subscription renewal, mid-cycle proration adjustment, and modular add-on charge, and allows instant payment execution or cancellation on open invoices.
Invoice Generation & Settlement Lifecycle
Important: Corporate billing metadata (
companyName,address,taxId, andvatNumberviaPUT /api/v1/billing/settingsandPUT /api/v1/billing/tax-profile) is snapshotted onto each invoice when finalized. Keep your tax details current in Company Settings prior to your renewal date.
Invoice Status (invoice status), Lifecycle & Line Kinds
Invoices track both an administrative lifecycle (invoice lifecycle state: DRAFT | OPEN | CLOSED | VOID) and a payment settlement status (invoice status), while itemized lines use invoice line item type (BASE_SUBSCRIPTION | ADD_ON | ACTIVE_PASSES_INCLUDED | ACTIVE_PASSES_OVERAGE | USAGE_EMAIL | USAGE_SMS | CREDIT_NOTE | ADJUSTMENT | TAX):
| invoice status | Accounting Meaning | Recommended Operator Action |
|---|---|---|
PAID | Payment was successfully captured and settled against the workspace's default payment method. | Download the official PDF tax receipt via /download for your accounting ledger. |
PENDING / PARTIALLY_PAID | Invoice has been finalized (OPEN) and is awaiting payment capture or partial balance settlement. | Verify your default payment instrument in Payment Methods and trigger POST /api/v1/billing/invoices/:id/pay. |
OVERDUE | Automated payment failed past the initial charge window (e.g., expired card or 3DS challenge needed). | Update card/Mandate in /settings/billing/payment-method and retry POST /api/v1/billing/invoices/:id/pay. |
CANCELLED / VOID | Invoice was canceled (POST /api/v1/billing/invoices/:id/cancel) or voided prior to collection. | No payment is owed; retain record for audit completeness if needed. |
Invoice Management API Reference (Billing API)
| Endpoint | HTTP Verb | Description |
|---|---|---|
/api/v1/billing/invoices | GET | Lists paginated workspace invoices (?page=1&limit=20). |
/api/v1/billing/invoices/:id | GET | Retrieves detailed invoice breakdown including line items (invoice line item type), tax rates, VAT notes, and payment attempts. |
/api/v1/billing/invoices/:id/download | GET | Streams the official itemized tax invoice as an application/pdf attachment. |
/api/v1/billing/invoices/:id/pay | POST | Settles or retries collection on a pending/overdue invoice using the workspace's active payment method. |
/api/v1/billing/invoices/:id/cancel | POST | Cancels an unpaid open invoice. |
/api/v1/billing/history | GET | Returns chronological workspace billing and payment event history. |
1. Inspecting Detailed Invoice Line Items & VAT (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>
Response 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. Streaming PDF Tax Invoices (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. Retrying Payment on an Open/Overdue Invoice (POST /api/v1/billing/invoices/:id/pay)
Update your default payment instrument in Settings -> Billing -> Payment Method (/settings/billing/payment-method), then trigger collection (no request body required):
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
}
Related Documentation
-
Configure corporate tax metadata and VAT IDs in Company Settings.
-
Add or update credit cards, PayPal, or Mobile Money in Payment Methods.
-
Export workspace data and compliance logs in Data Exports & Reporting.
