WHMCS\Billing\Invoice | WHMCS\Billing\Invoice | WHMCS Internal Class Documentation

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.

class Invoice extends AbstractModel

Properties summary

Type	Property	Description
protected	$table
protected	$dates
protected	$columnMap
	$timestamps
protected	$appends
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', 'Refunded', 'Draft', 'Collections', or 'Payment Pending'
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.
Collection\|Item	$items	The invoice items for this invoice.
Order	$order
Data	$data
float	$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.
string	$paymentGatewayName
float	$amountPaid

Methods summary

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.
HasMany	data()	Each invoice can have many one set of invoice data.
BelongsTo	order()	An invoice can belong to a single order.
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	scopePaymentPending(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
float	getBalanceAttribute()	Calculate balance remaining for the invoice.
string	getPaymentGatewayNameAttribute()	-
float	getAmountPaidAttribute()	-
bool	addPayment(float $amount, string $transactionId = '', float $fees = 0.0, string $gateway = '', bool $noEmail = false, Carbon $date = null)	-
array	getBillingValues()	-
bool	shouldRenewRun(integer $relatedId, string $registrationDate, string $type = 'Hosting')	Checks if the module renewal should run for a provided related id, registration date and type of item.

Details

`BelongsTo client ()`

Each invoice belongs to one client.

Return Value

BelongsTo

`hasMany transactions ()`

Each invoice can have many transactions.

Return Value

hasMany

`HasMany items ()`

Each invoice can have many line items.

Return Value

HasMany

`HasMany data ()`

Each invoice can have many one set of invoice data.

Return Value

HasMany

`BelongsTo order ()`

An invoice can belong to a single order.

Return Value

BelongsTo

`Builder scopeUnpaid (Builder $query)`

Where status is unpaid.

Parameters

Builder

$query

Return Value

Builder

`Builder scopeOverdue (Builder $query)`

Where status is overdue.

Parameters

Builder

$query

Return Value

Builder

`Builder scopePaid (Builder $query)`

Where status is paid.

Parameters

Builder

$query

Return Value

Builder

`Builder scopeCancelled (Builder $query)`

Where status is cancelled.

Parameters

Builder

$query

Return Value

Builder

`Builder scopeRefunded (Builder $query)`

Where status is refunded.

Parameters

Builder

$query

Return Value

Builder

`Builder scopeCollections (Builder $query)`

Where status is collections.

Parameters

Builder

$query

Return Value

Builder

`Builder scopePaymentPending (Builder $query)`

Where status is collections.

Parameters

Builder

$query

Return Value

Builder

`Builder scopeMassPay (Builder $query, bool $isMassPay = true)`

Where the invoice does not contain a line item that is of type "Invoice".

Parameters

Builder	$query
bool	$isMassPay	True if you want to find only Mass Pay invoices, false only non Mass Pay

Return Value

Builder

`Builder scopeWithLastCaptureAttempt (Builder $query, Carbon $date)`

Where the last capture date is on a specific date

Parameters

Builder	$query
Carbon	$date	The carbon object for the date to obtain data for

Return Value

Builder

`float getBalanceAttribute ()`

Calculate balance remaining for the invoice.

Return Value

float

`string getPaymentGatewayNameAttribute ()`

Return Value

string

`float getAmountPaidAttribute ()`

Return Value

float

`bool addPayment (float $amount, string $transactionId = '', float $fees = 0.0, string $gateway = '', bool $noEmail = false, Carbon $date = null)`

Parameters

float	$amount
string	$transactionId
float	$fees
string	$gateway
bool	$noEmail
Carbon	$date

Return Value

bool

Exceptions

NotServicable
Fatal

`array getBillingValues ()`

Return Value

array

`bool shouldRenewRun (integer $relatedId, string $registrationDate, string $type = 'Hosting')`

Checks if the module renewal should run for a provided related id, registration date and type of item.

Parameters

integer	$relatedId	The id of the item for the invoice being paid. tblhosting.id or tblhostingaddons.id
string	$registrationDate	in mysql date format
string	$type	Either one of Hosting or Addon. Exception will be thrown for other item types.

Return Value

bool

Exceptions

NotServicable