A customer's invoice.
The Invoice is the central mechanic upon which the entire WHMCS billing process is built upon. Orders request Services based on Products, which are turned into Invoices to handle payments. Future payments are then made against invoices until such time as the Client makes a CancellationRequest for the Product.
Each Invoice is attached to a specific clientId, and contains one or more invoice line items which actually define the products and prices paid on the invoice.
Tax Rules are configured in Setup -> Payments -> Tax Rules.
Multiple tax rules from each level may be valid for an Invoice, but only the lowest-numbered-ID tax rule will actually be applied to the Invoice.
Note that $id and $invoiceNumber are completely separate entities. The $id is used internally to track the invoice, while the $invoiceNumber is provided to the client and may be used for other tracking purposes; for example, VAT tax compliance.
|int||$id||Unique Internal Invoice ID number. Should not be confused with the invoiceNumber, which is displayed to the client.|
|int||$clientId||ID number of the client this invoice is addressed to.|
|string||$invoiceNumber||Invoice number displayed to customer. Custom formatted string configured in General Settings -> Invoices Tab -> Sequential Invoice Number Format.|
|Carbon||$dateCreated||Date this invoice was created.|
|Carbon||$dateDue||Date this invoice is considered "Due."|
|Carbon||$datePaid||Date this invoice was marked as "Paid."|
|Carbon||$lastCaptureAttempt||Date a capture was last attempted for this invoice (if applicable)|
|float||$subtotal||Total of all items in this invoice.|
|float||$credit||If the client has credit on hand, this is the amount of credit applied to this invoice.|
|float||$tax1||Amount of tax due, based on lowest ID number "Level 1" Tax Rule applied to this invoice.|
|float||$tax2||Amount of tax due, based on lowest ID number "Level 2" Tax Rule applied to this invoice. Level 2 Rules may or may not be calculated as compound tax.|
|float||$total||Total due on this invoice. Subtotal - Credit + Tax1 + Tax 2. Use this total instead of calculating your own as Level 2 taxes may or may not be compounded.|
|float||$taxRate1||Level 1 Tax rate applied to this invoice.|
|float||$taxRate2||Level 2 Tax rate applied to this invoice.|
|string||$status||English language internal name of the status of this invoice from this set: 'Paid', 'Unpaid', 'Cancelled', and 'Refunded'|
|string||$paymentGateway||Internal name of payment gateway assigned to this invoice.|
|string||$adminNotes||Free-form text provided by, and expected to be viewable only to, the admin.|
|Client||$client||Client object for which this invoice is due.|
|int||$balance||Balance still due on this invoice. If a client makes partial payments toward this invoice, those payments against the total will be reflected here.|
|Return Type||Method Name||Description|
|BelongsTo||client()||Each invoice belongs to one client.|
|hasMany||transactions()||Each invoice can have many transactions.|
|HasMany||items()||Each invoice can have many line items.|
|Builder||scopeUnpaid(Builder $query)||Where status is unpaid.|
|Builder||scopeOverdue(Builder $query)||Where status is overdue.|
|Builder||scopePaid(Builder $query)||Where status is paid.|
|Builder||scopeCancelled(Builder $query)||Where status is cancelled.|
|Builder||scopeRefunded(Builder $query)||Where status is refunded.|
|Builder||scopeCollections(Builder $query)||Where status is collections.|
|Builder||scopeMassPay(Builder $query, bool $isMassPay = true)||Where the invoice does not contain a line item that is of type "Invoice".|
|Builder||scopeWithLastCaptureAttempt(Builder $query, Carbon $date)||Where the last capture date is on a specific date|
|int||getBalanceAttribute()||Calculate balance remaining for the invoice.|
Each invoice belongs to one client.
Each invoice can have many transactions.
Each invoice can have many line items.
scopeUnpaid (Builder $query)
Where status is unpaid.
scopeOverdue (Builder $query)
Where status is overdue.
scopePaid (Builder $query)
Where status is paid.
scopeCancelled (Builder $query)
Where status is cancelled.
scopeRefunded (Builder $query)
Where status is refunded.
scopeCollections (Builder $query)
Where status is collections.
scopeMassPay (Builder $query, bool $isMassPay = true)
Where the invoice does not contain a line item that is of type "Invoice".
scopeWithLastCaptureAttempt (Builder $query, Carbon $date)
Where the last capture date is on a specific date
Calculate balance remaining for the invoice.