Revision as of 14:11, 1 May 2020

Having an understanding of WHMCS's billing and invoicing logic, core elements of the software, will enable years of smooth and trouble-free operation.

Ordering

When a new visitor places an order, the system creates several new records, which contain the various pieces of information on the order form:

• A client record, which stores the customer's contact details and payment preferences.
• The service and domain record(s), which contain the details of the service the client selected on the order form.
• An invoice record, which records the amount to pay, when it is due, and how to make payment.
• An order record, which ties all of the above together and records the fraud report details (if you enable them). The order is a static record which reflects the prices and items at the time of ordering. The order won't reflect subsequent changes.

Invoicing

Initial Invoice

When an initial order creates an invoice, the default behavior is that the invoice is due on the day of ordering. The exception to this is when you use the Order Grace Days setting, in which case the system will set the invoice due date x days into the future.

Upon payment of the initial invoice, the system checks the associated products to determine whether to take action automatically, based upon the Module Settings. This could be one of the following actions:

• Automatically set up the product as soon as a client places an order.
• Automatically set up the product as soon as you receive the first payment.
• Automatically set up the product when you manually accept a pending order.
• Do not automatically set up this product.

The system then increments the service's Next Due Date value forward one billing cycle (for example, 1 month, 3 months, 6 months, 1 year, 2 years, or 3 years).

Renewal Invoices

The Next Due Date of the service depends on the date at which the next payment is due. When the cron job executes the daily automation tasks, the system:

• Analyzes the Next Due Date of all Active, Pending and Suspended services.
• Determines whether the date is equal to or less than the number of days in the future, based on the Invoice Generation setting.
• Ensures no invoice item exists for the service on the next due date.
• Generates a new invoice if the system evaluates the above points as true.
• Triggers the InvoiceCreation Action Hook point.
• Triggers the InvoiceCreationPreEmail Action Hook point.
• Sends the Invoice Created email to the client.
• Triggers the InvoiceCreated Action Hook point.
• Increments the Next Invoice Date of the service by one billing cycle.

In this way, WHMCS will never generate two invoices for a given product, service, or domain with the same due date, even if you have cancelled or deleted the original invoice.

As the Next Due Date is incremented forward based upon the previous value, this means paying an invoice after the due date will not change the client's renewal date to reflect the date of payment. A service always invoices for a contiguous period without gaps. This prevents a situation in which a customer might hope to avoid paying for a service by intentionally paying late.

Continuous Invoice Generation

When you enable the Continuous Invoice Generation option in the general settings, it alters the invoice generation logic so that the system creates renewal invoices even if the previous one is unpaid.

Checking a hidden field in the service record, Next Invoice Date, enables this. The Next Invoice Date field maintains a separate record of the due date for next invoice to generate. The Next Due Date value determines the next invoice to be paid.

In this mode, when the cron job executes the daily automation tasks, it:

• Analyzes the Next Invoice Date of all Active, Pending and Suspended services.
• Determines whether the date is equal to or less than the number of days in the future, based on the Invoice Generation setting.
• Ensures no invoice item exists for the service on the next invoice date.
• Generates a new invoice if the system evaluates the above points as true.
• Triggers the InvoiceCreation Action Hook point.
• Triggers the InvoiceCreationPreEmail Action Hook point.
• Sends the Invoice Created email to the client.
• Triggers the InvoiceCreated Action Hook point.
• Increments the Next Invoice Date of the service by one billing cycle.

In this way, WHMCS maintains a separate record of which invoice to generate and which payment is due.

Payments

A transaction that fully pays the balance on an invoice, reducing it to 0.00 and marking it paid, triggers automation on payment. This means that editing an invoice and changing the status to Paid will not trigger automation. Upon adding payment to an invoice for a product, service, or domain, the system:

• Enters a transaction into the database.
• Triggers the AddTransaction Action Hook point.
• Subtracts the transaction amount from the invoice balance.
• Marks the invoice as paid if the invoice balance is now 0.
• Changes the invoice status to Paid.
• Triggers the InvoicePaidPreEmail Action Hook point.
• Sends a payment confirmation email to the client.
• Increments the Next Due Date of the associated service or domain by one billing cycle.
• Triggers the InvoicePaid Action Hook point.

Overpayments

If a transaction includes an amount greater than the balance of the invoice, the system:

• Records the entire transaction against the invoice, making the balance negative.
• Marks the invoice as paid.
• Credits the difference between the balance and the transaction amount to the client's account.
• Changes the credit description format to Invoice # Overpayment.

Sometimes, fixed payments services (such as PayPal Subscriptions and 2Checkout Recurring Payments) can send a payment when no payment is due. In these situations, the system:

• Records the entire transaction against the invoice that originally created the billing agreement, making the balance negative.
• Credits the full transaction amount to the client's account.
• Changes the credit description format to Invoice # Overpayment.

Refunds

You can issue refunds on transactions for invoices via the Refunds tab. When a you initiate a refund, the system:

• Performs the selected refund action, which could be either of the following actions:
  • It sends a refund command to the payment gateway (if it supports it).
  • It adds a credit to the client's account with the description Credit from Refund of Invoice ID #.
• Records a negative transaction against the invoice.
• Triggers the AddTransaction Action Hook point.
• Increases the invoice's balance by the refunded amount.
• Changes the invoice's status to Refunded if system refunded the full balance.
• Triggers the InvoiceRefunded Action Hook point.
• Sends the Invoice Refund Confirmation email to the client.

If the refunded transaction resulted in a credit to the client's account, you must choose how to handle the credit:

• Remove the refunded amount from the credit balance.
• Do not change the credit.

Payment Reversals

When issuing a refund, there is also the option to reverse the payment. This is useful when you want to reverse the automated actions that the payment triggered, typically in the event of a payment dispute or chargeback.

The actions that the system takes when reversing a payment are context sensitive and depend upon your payment reversal settings. For an in-depth discussion of this feature, refer to the Payment Reversals page.

Billing Cycles

A billing cycle is a calendar period, so "1 month" is not a consistent period of days. When you agree to bill by the month, you are charging the same amount of money for different amounts of service. WHMCS uses the PHP date function's computation to determine the next due date. It adds a month and returns the date, which becomes the Next Due Date.

February

The shorter length of February can cause some unique behaviour that does not happen for the other 11 months of a year:

Suspension

The Next Due Date for the service controls the date of service suspension. When the cron job executes the daily automation tasks, the system:

• Analyzes he Next Due Date of all Active and Pending services.
• Determines whether the date is equal to or less than the number of days in the future in the Suspension Days setting.
• Determines whether Automated Suspension is enabled in Automation Settings.
• Triggers the PreModuleSuspend Action Hook point if the above items evaluate to true.
• Suspends the services.
• Triggers the AfterModuleSuspend Action Hook point if the module returns a success response.
• Triggers the AfterModuleSuspendFailed Action Hook point If the module returns a failed response.

Unsuspension

When payment is made against an invoice for a service with the Suspended status, the system can automatically unsuspend the service. In addition to the actions in the Payments section, the system:

• Associates the invoice with a service in Suspended status.
• Enables the Enable Unsuspension option in Automation Settings.
• Applies a suspension reason of "Overdue on Payment" to the service.
• Triggers the PreModuleUnsuspend Action Hook point if the points above evaluate to true.
• Unsuspends the service.
• Triggers the AfterModuleUnsuspend Action Hook point if the module returns a success response.
• Triggers the AfterModuleUnsuspendFailed Action Hook point if the module returns a failed response.

Continuous Invoice Generation

When you use it in conjunction with continuous invoice generation, paying a recent invoice while leaving an older invoice unpaid will keep the service suspended. The exception is if the payment were to increment the Next Due Date forward to a date at which the service was no longer within the Suspension date range. In that case, the service would be unsuspended.

Termination

The Next Due Date of the service controls the date when the system terminates services. When the cron job executes the daily automation tasks, the system:

• Analyzes the Next Due Date of all Active, Suspended and Pending services.
• Determines whether the date is equal to or less than the number of days in the future for the Termination Days setting.
• Determines whether you enabled Automated Termination in Automation Settings.
• Triggers the PreModuleTerminate Action Hook point if the above points evaluate to true.
• Terminates the services.
• Triggers the AfterModuleTerminate Action Hook point if the module returns a success response.
• Triggers the AfterModuleTerminateFailed Action Hook point if the module returns a failure response.