WHMCS's Invoice Class is a central component of the WHMCS billing system. It provides a structured way to manage and process invoices for clients. Here's a comprehensive overview of the Invoice Class and its functionalities:
Overview:
The Invoice Class in WHMCS is the backbone of the entire billing process. It is built upon the following principles:
- Orders request services based on products.
- These orders are then converted into invoices to handle payments.
- Future payments are made against these invoices until the client requests a cancellation for the product.
- Each invoice is attached to a specific client ID and contains one or more invoice line items that define the products and prices paid on the invoice.
- Tax rules can be configured in the WHMCS setup under Payments -> Tax Rules. Multiple tax rules may apply to an invoice, but only the lowest-numbered-ID tax rule will be applied.
Properties:
$id: Unique Internal Invoice ID number. This should not be confused with the$invoiceNumber, which is displayed to the client.$clientId: ID number of the client this invoice is addressed to.$invoiceNumber: Invoice number displayed to the client. This is a custom formatted string configured in General Settings -> Invoices Tab -> Sequential Invoice Number Format.$dateCreated: Date the invoice was created.$dateDue: Date the invoice is considered "Due."$datePaid: Date the invoice was marked as "Paid."$subtotal: Total of all items in the invoice.$credit: Amount of credit applied to the invoice if the client has any credit on hand.$tax1 & $tax2: Amount of tax due based on the applied tax rules.$total: Total due on the invoice, calculated as Subtotal - Credit + Tax1 + Tax2.$taxRate1 & $taxRate2: Tax rates applied to the invoice.$status: Status of the invoice, which can be 'Paid', 'Unpaid', 'Cancelled', or 'Refunded'.$paymentGateway: Internal name of the payment gateway assigned to the invoice.$adminNotes: Notes provided by the admin, viewable only to the admin.$client: Client object for which the invoice is due.$balance: Balance still due on the invoice, reflecting any partial payments made by the client.
Methods:
client(): Each invoice belongs to one client.transactions(): Each invoice can have multiple transactions.items(): Each invoice can have multiple line items.scopeUnpaid(Builder $query): Filters invoices where the status is unpaid.scopeOverdue(Builder $query): Filters invoices where the status is overdue.scopePaid(Builder $query): Filters invoices where the status is paid.scopeCancelled(Builder $query): Filters invoices where the status is cancelled.scopeRefunded(Builder $query): Filters invoices where the status is refunded.
For those looking to deeply integrate or customize their WHMCS invoicing system, understanding the Invoice Class and its properties and methods is crucial. It provides a structured way to manage invoices, from creation to payment, and offers flexibility for developers to tailor the system to their specific needs.
Link to KB article 8 (Invoices)
Link to KB article 9 (Invoice - Billing - WHMCS Internal Class Documentation)
