Billing Logic
Billing and invoicing are two of the most important tasks that WHMCS can automate for you. It is important to understand the logic that these systems use so that you can make the best possible configuration choices.
The Billing Process
The billing and invoicing process in WHMCS follows the same general process for all orders:
- Ordering — A client places an order or an admin places an order on the client’s behalf.
- Invoicing — The system generates an invoice for the order, either through automation or when an admin generates an invoice manually.
- Payment — The client pays the invoice.
- Provisioning — If the product uses a provisioning module, WHMCS provisions the service according to the product’s settings.
WHMCS’s billing and invoicing logic also controls suspension, unsuspension, and termination for applicable services. Suspension, unsuspension, and termination can happen on request or due to lack of payment in relation to a client’s Next Due Date.
Ordering
Orders can enter your system through many methods. In the Admin Area, admins can create orders for new or existing clients. New customers and existing clients can order products through your store and the Client Area.
When a new customer places an order, the system creates several new records, which contain the various pieces of information on the order form:
Created Record | Description | View At |
---|---|---|
Client Record | This record stores the customer’s contact details and payment preferences. | The client profile Summary tab. |
Service or Domain Records | These records contain the details of the service that the client selected. | The client profile Products/Services and Domains tabs. |
Invoice Record | This record includes the amount to pay, when it is due, and how to make payment. | The client profile Invoices tab or Billing > Invoices. |
Order Record | This record contains all of the above information in addition to any fraud report details (if you have enabled fraud protection). This is a static record that reflects the prices and items at the time of ordering. It will not reflect subsequent changes. | Orders > List All Orders |
Invoicing
When an initial order creates an invoice, the invoice is due on the order date by default.
If you enabled Order Grace Days in the Ordering tab at Configuration () > System Settings > General Settings, the system will set the invoice due date according to this setting.
Invoice Generation and the Next Due Date
The Next Due Date of the service determines 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 value for:
- All services in the Active and Suspended statuses.
- All domains in the Active and Pending statuses, if their Do Not Renew setting is OFF.
- Determines whether the date for each service is equal to or less than the number of days in the future, based on the Invoice Generation setting.
- Ensures that no invoice item exists for each of these services for 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 value for the service by one billing cycle.
Using this logic, 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.
Because the system increments the Next Due Date value forward using the previous value, paying the invoice will not change the client’s renewal date, regardless of the date of payment. Services will always invoice for a contiguous period.
Continuous Invoice Generation
When you enable Continuous Invoice Generation, the system creates invoices regardless of whether unpaid invoices exist for the service.
- The system generates invoices if the service status is Active or Suspended.
- The system will not generate invoices if the service status is Pending, Completed, Cancelled, or Terminated.
For example, a customer might order a monthly product in January, receive their January invoice, and pay it. The system would generate their next invoice in February:
- With Continuous Invoice Generation, the system will create a March invoice regardless of whether the customer paid the February invoice.
- If you have disabled Continuous Invoice Generation, the system will not create a March invoice if the February invoice is unpaid.
You can enable Continuous Invoice Generation in the Invoices tab at Configuration () > System Settings > General Settings.
The Next Invoice Date value for services maintains a separate record of the due date for next invoice to generate. The Next Due Date value determines the next invoice to pay.
If you have enabled Continuous Invoice Generation, when the cron job executes the daily automation tasks, it:
- Analyzes the Next Invoice Date value for all Active, Pending, and Suspended services.
- Uses the Invoice Generation setting to determine whether the date is equal to or less than the number of days in the future.
- Ensures that 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.
For more information about this setting, see Invoices.
Payment
A transaction that fully pays the balance on an invoice, reducing it to 0.00
and marking it paid, triggers automation on payment. Editing an invoice and changing the status to Paid will not trigger automation.
When a client pays 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.For payments that exceed the invoice amount, see Overpayments below.
- Marks the invoice as paid and changes the invoice status to Paid if the invoice balance is now
0
. - 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.
After payment of the initial invoice, the system determines whether to provision the service automatically using the configuration in the Module Settings tab at Configuration () > System Settings > Products/Services.
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 in an invoice.
When 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 you issue a refund, you have the option to reverse the payment. This is useful when you want to reverse the automated actions that the payment triggered, typically due to a dispute.
The actions that the system takes when reversing a payment are context sensitive and depend on your payment reversal settings.
For more information, see Payment Reversals.
Affiliate Commission Reversals
When you issue a refund, you can also reverse any affiliate commissions. This helps you ensure that you do not pay commissions to affiliates unless you also received payment for the transaction.
When you refund a transaction, one of the following scenarios will occur:
- If you are giving a full refund, WHMCS will perform the reversal automatically.
- If you are giving a partial refund, you can choose whether to perform the reversal.
For more information on affiliate commission reversals and delays, see Affiliates.
Billing Cycles
The following billing cycles are available for products or services and product addons:
- One Time
- Monthly
- Quarterly
- Semi-Annually
- Annually
- Biennially
- Triennially
A billing cycle is a calendar period. Due to this, a monthly billing cycle 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.
The shorter length of February can cause some unique behavior that does not happen for the other months of a year:
Order Date | Renewal Date | Number of Days |
---|---|---|
January 29 | March 1 | 31 days |
January 30 | March 2 | 31 days |
January 31 | March 3 | 31 days |
February 1 | March 1 | 28 days |
February 2 | March 2 | 28 days |
February 3 | March 3 | 28 days |
Suspension, Unsuspension, and Termination
Suspension
The Next Due Date value for the service controls the date of service suspension. When the cron job executes the daily automation tasks, the system:
- Analyzes the Next Due Date value 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 at Configuration () > System Settings > Automation Settings.
- Triggers the
PreModuleSuspend
action hook point if the above items evaluate to true. - Suspends the services.
- Applies a suspension reason of
Overdue on Payment
to the service. - Triggers the
AfterModuleSuspend
action hook point if the module returns a success response, or triggers theAfterModuleSuspendFailed
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 Payments above, the system:
- Analyzes the invoices for a service in the Suspended status with a Suspension Reason of
Overdue on Payment
. - Checks whether Enable Unsuspension is enabled at Configuration () > System Settings > Automation Settings.
- 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, or triggers theAfterModuleUnsuspendFailed
action hook point if the module returns a failed response.
If you have enabled Continuous Invoice Generation, a customer could pay a more recent invoice but leave an older invoice unpaid. In this case, the system will not unsuspend the service unless the payment increments the Next Due Date forward to a date that is not within the suspension date range.
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 value 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.
- Checks whether you enabled Automated Termination in Configuration () > System Settings > 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, or triggers theAfterModuleTerminateFailed
action hook point if the module returns a failure response.
Last modified: September 23, 2024