Invoicing & Hosted Invoices

SubsManager features a multi-tenant invoicing engine. It generates official tax invoices for recurring cycles, offline bank transfers, and free trial transitions. Invoices can be retrieved programmatically via REST API or viewed via a hosted, print-optimized web link.

1. Querying Invoices via API

Integrators can fetch invoices to display billing history and payment statuses inside customer-facing account settings.

List Invoices

• Endpoint: GET /invoices
• Headers: Authorization: Bearer ap_...
• Query Parameters:
  • externalId: Filter by your client user ID
  • status: draft, open, paid, uncollectible, void
  • limit: Default 50
  • skip: Default 0

Request:

GET /api/v1/invoices?externalId=usr_99182&status=paid
Authorization: Bearer ap_live_your_api_key

Response (200 OK):

{
  "success": true,
  "data": {
    "invoices": [
      {
        "_id": "67db0104...",
        "invoiceNumber": "INV-2026-0042",
        "status": "paid",
        "amount": 299.00,
        "currency": "ZAR",
        "issueDate": "2026-10-01T00:00:00.000Z",
        "dueDate": "2026-10-08T00:00:00.000Z",
        "paidAt": "2026-10-02T14:32:00.000Z",
        "invoiceUrl": "https://subsmanager.vertueal.com/invoices/67db0104...",
        "items": [
          {
            "description": "Professional Plan (monthly)",
            "quantity": 1,
            "unitPrice": 299.00,
            "amount": 299.00
          }
        ],
        "bankingDetailsSnapshot": {
          "bankName": "Standard Bank",
          "accountName": "Vertueal Technologies",
          "accountNumber": "1019283746",
          "branchCode": "051001",
          "swiftCode": "SBZAJJ"
        },
        "metadata": {
          "referenceNumber": "SUB-J92K4M"
        }
      }
    ],
    "total": 1,
    "limit": 50,
    "skip": 0
  }
}

2. Hosted Printable Invoices (/invoices/:id)

Every invoice generated by SubsManager includes a public hosted URL:

https://subsmanager.vertueal.com/invoices/:id

Key Highlights of the Hosted Invoice View:

• Print to PDF Optimization: Features a dedicated @media print CSS stylesheet. When the user clicks "Print Invoice" or presses Ctrl+P / Cmd+P, all navigation, headers, and buttons disappear, formatting the invoice into a crisp, single-page standard tax document.
• Responsive Layout: Formats cleanly on mobile screens for users viewing billing notices on smart phones.
• Embedded Banking Details: Prominently highlights the business bank name, account number, branch code, and unique payment reference for offline EFT deposits.
• Real-Time Payment Badges: Displays green PAID badges with verified timestamps or amber DUE badges with clear deadlines.