WHMCS\Billing\Invoice

Class · extends AbstractModel · implements ImmutableModelInterface, TaxableInterface

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.

• ImmutableModelTrait

public static function factoryWithoutStatusIndex(): self

Returns self

public static function boot()

public function isImmutable(): bool

public function throwImmutabilityException(string $message = '', string $column = ''): never

Parameters

Returns never

public static function validStatusTransitionMap(): array

Returns array<string, — array<string>>

public static function terminalStatuses(): array

Returns array<string>

public function isStatusTransitionAllowed(string $toStatus): bool

public function validateMutability(?string $attribute): void

public function getViewInvoiceUrl(?array $additionalQueryStringParams = null): string

Get view invoice url.

Parameters

Returns string

public function getClientViewLinkMarkup(?string $targetValue = null): string

public function getAdminViewLinkMarkup()

public function getEditInvoiceUrl(?array $additionalQueryStringParams = null): string

Get Edit Invoice URL.

Parameters

Returns string

public function getEditInvoiceTabUrl(int $tab, $additionalQueryStringParams = null): string

public function getRefundInvoiceUrl(?array $additionalQueryStringParams = null): string

public function getInvoiceNumber()

public function getCurrency()

Get currency object for the invoice.

Returns array

public function getCurrencyCodeAttribute()

Get currency code.

Returns string

public function getCurrencyModel(): ?Currency

public function client()

Each invoice belongs to one client.

Returns \Illuminate\Database\Eloquent\Relations\BelongsTo

public function transactions()

Each invoice can have many transactions.

Returns \Illuminate\Database\Eloquent\Relations\hasMany

public function items()

Each invoice can have many line items.

Returns \Illuminate\Database\Eloquent\Relations\HasMany

public function snapshot()

Each invoice can have one set of invoice snapshot data.

Returns \Illuminate\Database\Eloquent\Relations\hasOne

public function order()

An invoice can belong to a single order.

Returns BelongsTo

public function servicesProduct(): BelongsToMany

public function servicesAddon(): BelongsToMany

public function servicesDomain(): BelongsToMany

public function scopeUnpaid(Builder $query)

Where status is unpaid.

Parameters

Returns \Illuminate\Database\Eloquent\Builder

public function scopeOverdue(Builder $query)

Where status is overdue.

Parameters

Returns \Illuminate\Database\Eloquent\Builder

public function scopePaid(Builder $query)

Where status is paid.

Parameters

Returns \Illuminate\Database\Eloquent\Builder

public function scopeCancelled(Builder $query)

Where status is cancelled.

Parameters

Returns \Illuminate\Database\Eloquent\Builder

public function scopeRefunded(Builder $query)

Where status is refunded.

Parameters

Returns \Illuminate\Database\Eloquent\Builder

public function scopeCollections(Builder $query)

Where status is collections.

Parameters

Returns \Illuminate\Database\Eloquent\Builder

public function scopePaymentPending(Builder $query)

Where status is payment-pending.

Parameters

Returns \Illuminate\Database\Eloquent\Builder

public function scopeUnpaidOrPaymentPending(Builder $query)

Where status is unpaid or payment-pending.

Parameters

Returns \Illuminate\Database\Eloquent\Builder

public function scopeMassPay(Builder $query, $isMassPay = true)

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

Parameters

Returns \Illuminate\Database\Eloquent\Builder

public function scopeWithLastCaptureAttempt(Builder $query, Carbon $date)

Where the last capture date is on a specific date

Parameters

Returns \Illuminate\Database\Eloquent\Builder

public function getBalanceAttribute()

Calculate balance remaining for the invoice.

Returns float

public function getInvoiceAmountAttribute(): float

public function getPaymentGatewayNameAttribute()

Returns string

public function getAmountPaidAttribute()

Returns float

public function hasRemainingBalanceDue(): bool

Remaining balance is the invoice total minus the sum of all transactions towards the invoice, with consideration of the currency's decimal/no-decimal format.

Ex. if the invoice total was set to 666.66, and the payment history was in Japanese Yen (JPY), once there is enough transactions totalling >= 666.50, this method would return FALSE. If the payment history was in USD, the target sum would be >= 666.66 for this method to return FALSE.

Returns bool

public function addPayment($amount, $transactionId = '', $fees = 0.0, $gateway = '', $suppressEmail = false, Carbon $date = null)

"add a payment" means to record a transaction for an invoice, and per this method, also means updating the invoice status, managing overpayments, updating services referenced in the invoice, and other invoice-adjacent observable events.

Parameters

Returns bool

public function addPaymentIfNotExists($amount, $transactionId = '', $fees = 0.0, $gateway = '', $noEmail = false, Carbon $date = null)

Parameters

Returns bool

public function getBillingValues()

Calculate recurring billing data for each invoice item. Each row data subarray can contain additional fields if the payment doesn't cover the entire amount.

Returns array — payment data [ 'overdue' => bool, [ 'itemId' => string, 'amount' => string, 'setupFee' => string, 'recurringCyclePeriod' => float, 'recurringCycleUnits' => "Months"|"Years"|"Days", 'description' => string, 'lineItemAmount' => string, // If a balance remains on the invoice, the following keys will be present: 'firstPaymentAmount' => string, 'firstCyclePeriod' => float, 'firstCycleUnits' => "Months"|"Years"|"Days" ], [ 'itemId' => string, // ... ] ]

public function shouldRenewRun($relatedId, $registrationDate, $type = 'Hosting')

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

Parameters

Returns bool

public function vat()

Returns Vat

public static function newInvoice($clientId, $gateway = null, $taxRate1 = null, $taxRate2 = null)

Create a new invoice in Draft and return the instance to be updated and saved.

Parameters

Returns Invoice

public function setStatusUnpaid()

Set invoice status to unpaid.

Returns Invoice

public function setStatusPending()

Set invoice status to payment pending.

Returns Invoice

public function setStatusRefunded()

Set invoice status to refunded.

Returns Invoice

public function setStatusCancelled()

Set invoice status to cancelled.

Returns Invoice

public function data()

Each invoice can have one set of invoice data.

Returns \Illuminate\Database\Eloquent\Relations\hasOne

public function transactionHistory()

Returns \Illuminate\Database\Eloquent\Relations\HasMany\|History[]

public function debitNotes()

Returns Builder\|DebitNote[]

public function payMethod()

Returns \Illuminate\Database\Eloquent\Relations\BelongsTo\|PayMethod

public function getPayMethodRemoteToken()

Returns string

public function setPayMethodRemoteToken($remoteToken)

public function deletePayMethod()

public function convertLocalCardToRemote($remoteToken)

public function convertLocalBankAccountToRemote($remoteToken)

public function saveRemoteCard($cardLastFour, $cardType, $expiryDate, $remoteToken)

public function saveRemoteBankAccount($bankName, $remoteToken)

public function cart()

Build a cart object based on the current invoice.

Returns CartCalculator

public function runCreationHooks($source)

Run invoice creation hooks.

Parameters

Returns self

public function getSubscriptionIds($paymentMethods = null)

Get subscription IDs from items that belong to this invoice.

Parameters

Returns SupportCollection

public function saveSubscriptionId($subscriptionId)

Save subscription ID.

Parameters

Returns self

public function scopeSubscriptionId(Builder $query, $subscriptionId)

Where the invoices contain items that have a given subscription ID.

Parameters

Returns \Illuminate\Database\Eloquent\Builder

public function getLink()

public function getAdminViewLink(): string

public function setPaymentMethod($gatewayName)

Set the invoice Payment Method.

Parameters

Returns $this

public function setPayMethodId($payMethodId)

Set the Pay Method ID for the invoice.

Parameters

Returns $this

public function clearPayMethodId()

Clear the associated Pay Method

Returns $this

public function getTaxrateAttribute()

public function getTaxrate2Attribute()

public function getGatewayInterface(): Gateway

Returns Gateway

public function updateInvoiceTotal()

Update invoice totals will refresh the model loaded and then process all the invoice items and appropriate taxes to update the totals on the invoice and then save. A save is required prior to calling this method to ensure any 'dirty' data is not lost. The save should happen before any invoice hooks are run to ensure that any hook functions have the most up to date information on the invoice at the point of the hook running.

public function calculateInvoiceTotal()

public function removeCredit($amount)

Parameters

public function paidAffiliateCommissions(): Relation

public function pendingAffiliateCommissions(): Relation

public function requiresPayment(): bool

Is the invoice in a state in which initiating payment against it is desirable?

Returns bool

public function isUnpaid(): bool

Is the invoice marked as unpaid?

Returns bool

public function isAwaitingPayment(): bool

Is the invoice expecting a previously initiated payment's completion?

Returns bool

public function isDraft(): bool

public function isPaid(): bool

public function isCollections(): bool

public function isRefunded(): bool

public function isCancelled(): bool

public function canPaymentBeApplied(): bool

Is the invoice in a state in which applying a payment is expected and possible.

Returns bool

public function isProformaInvoice(): bool

public function productGroups(): SupportCollection

All groups related to products of services itemized in the invoice.

Returns SupportCollection<int, — Group> Group keyed by Group ID

public function billingPaymentGateway(): ?PaymentGatewayInterface

If the invoice has a PaymentGateway assigned, return it, otherwise NULL.

NOTE: the instance of PaymentGatewayInterface may not be serviceable or active.

Returns PaymentGatewayInterface\|null — NULL if nothing assigned

public function allAvailablePaymentGatewayOptions(): Collection

Legacy understanding, and limited contextual consideration, of "All Gateways" for use with this invoice.

Callers should consider using {@see Invoice::paymentGatewayOptionsFactory()} and refining a list appropriate to their context.

Considerations for the returned collection:

• Excluded: non-active or non-serviceable PaymentGateway on the system
• Excluded: PaymentGateways which are "hidden"
• Excluded: The disallowed PaymentGateways of Product Groups related to invoice's line item Services.
• Included: The payment gateway currently assigned to the invoice, if active and serviceable (regardless of "hidden" state)

Note: Currency support is not a consideration due to external contexts

Returns Collection<string, — PaymentGatewayInterface>

public function paymentGatewayOptionsFactory(): PaymentGatewayOptions

A PaymentGatewayOptions factory, primed with an instance of this class.

Returns PaymentGatewayOptions

public function adjustInvoiceForPaymentGatewayOptions(PaymentGatewayOptions $options): self

Inspect the invoice's assigned PaymentGateway relative to the provided PaymentGatewayOptions and update the payment method based on those options.

Parameters

Returns $this

public function credits(): HasMany

Returns HasMany

public function isFullLineItemSet(SupportCollection $lineItems): bool

Returns true if the provided collection of line items matches the full set of invoice line items (in no specific order)

Parameters

Returns bool

public function addPaymentForRemainingBalance()

"Mark Paid" with blind application of payment for the remaining balance.

Returns null\|Event\InvoicePayment;

public function allowances(): Allowances

public function getTax1Amount(): float

public function getTax2Amount(): float

public function getSubtotal(): float

public function getAppliedCreditAttribute(): float

public function appliedCreditAggregator()