Skip to content
Help Center Guide · Billing & Payments
3 min readVerified 2026-11-16

Invoices & Billing History

View monthly/annual billing records, download official PDF invoices, and preview upcoming renewal line items.

In This Guide

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

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
INVOICE LIFECYCLE, PDF STREAMING & RETRY SETTLEMENT
STAGE 01 BILLING CYCLE / PRORATION EVENT
Subscription Renewal, Plan Upgrade (change), or Add-On Subscription
Snapshots Legal Entity, Address & vatNumber/taxId (PUT/billing/settings)
STAGE 02 INVOICE STATE MACHINE (Billing API)
+[ PAID ] (Automatic Charge Succeeded) [ PENDING / OPEN ]-+[ OVERDUE ]POST/invoices/:id/pay (Awaiting Settlement) | (Uses Default Method)
+[ VOID / CANCELLED ] (Voided/Canceled Invoice)
STAGE 03 INVOICE RETRIEVAL & PDF STREAMING
GET/api/v1/billing/invoices (Paginated ?page=&limit= History)
GET/api/v1/billing/invoices/:id (Line Items, Credits, VAT/Tax Breakdown)
GET/api/v1/billing/invoices/:id/download (application/pdf Binary Stream)

Important: Corporate billing metadata (companyName, address, taxId, and vatNumber via PUT /api/v1/billing/settings and PUT /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 statusAccounting MeaningRecommended Operator Action
PAIDPayment 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_PAIDInvoice 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.
OVERDUEAutomated 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 / VOIDInvoice 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)

EndpointHTTP VerbDescription
/api/v1/billing/invoicesGETLists paginated workspace invoices (?page=1&limit=20).
/api/v1/billing/invoices/:idGETRetrieves detailed invoice breakdown including line items (invoice line item type), tax rates, VAT notes, and payment attempts.
/api/v1/billing/invoices/:id/downloadGETStreams the official itemized tax invoice as an application/pdf attachment.
/api/v1/billing/invoices/:id/payPOSTSettles or retries collection on a pending/overdue invoice using the workspace's active payment method.
/api/v1/billing/invoices/:id/cancelPOSTCancels an unpaid open invoice.
/api/v1/billing/historyGETReturns chronological workspace billing and payment event history.

1. Inspecting Detailed Invoice Line Items & VAT (GET /api/v1/billing/invoices/:id)

HTTP
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)

JSON
{
  "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)

HTTP
GET /api/v1/billing/invoices/inv_01933220-5a11-7e00-9c44-887766554433/download HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
HTTP
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):

HTTP
POST /api/v1/billing/invoices/inv_01933299-1b22-7c00-8d11-223344556677/pay HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
JSON
{
  "invoiceId": "inv_01933299-1b22-7c00-8d11-223344556677",
  "status": "PAID",
  "paidAt": "2026-11-16T10:36:45.000Z",
  "amountPaidCents": 17731
}

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.