How To Guides

This page contains step-by-step instructions for certain common scenarios that may occur while running a business. There are more tips, tricks and howto's in our forum.

Regenerate Historical Invoices

When switching from a manual billing system or software for which an import script is not available, you may want to have a record of past invoices that you issued before you started using WHMCS.

Once you have added the client and their service, navigate to the client's Products/Services tab and set the Next Due Date back to the date you want the first historical invoice to be due via their Products/Services tab and Save Changes. For example, if the client has an invoice every month starting in June, 2011, set it to 28/06/2011.

Click the Generate Due Invoices button from the summary page to create last year's invoice. When the system prompts you, select "No" so that the client doesn't receive a notification email.

Next, navigate to the Invoices tab, click the invoice, and then click the Add Payment tab to record the payment details per Transactions. Uncheck the "Send Email" option so the client doesn't receive a notification email.

This will cause the Next Due Date to increment forward one billing cycle, so in our example it will now be 28/06/2012. Click the "Generate Due Invoices" again and the system will create the June 2011 invoice.

Repeat this until the Next Due Date is showing the date the client's next payment is due.

Update Domain Pricing

Bulk Price Updater

Occasionally, it may be necessary to update the price of existing domain names or products in your system (for example, in line with wholesale price increases). There may also be times where it is desirable to increase the price of specific domain addons (for example, if you wish to start charging for ID Protection after previously offering it for free). You can achieve this with the Bulk Pricing Updater Addon and these instructions:

Begin by navigating to Setup > Addon Modules.
Locate and Activate the Bulk Pricing Updater addon (it may already be active, in which case you can skip this step).
Ensure that you have access to the module by scrolling down the page following activation and ensuring your admin role group (usually Full Administator) has the checkbox checked in the Access Control permissions for it.
Navigate to Addons > Bulk Pricing Updater to actually access the addon module.
Set your criteria and perform the pricing update. To do this:
- Step 1 — Choose the type of item you wish to make a pricing update to, which in this case is Domains.
- Step 2 — Specify the criteria for identifying the items you wish to change the pricing on by checking the corresponding TLD checkboxes.
  - Select the statuses you want to apply the change to. We recommend only Pending, Pending Transfer, and Active statuses. Expired and Cancelled domains won't receive invoices again.
  - Select the Registration Period you want to apply the change to (for example, one or two years). You will need to run an update for each pricing term you offer.
  - If you only wish to change the price of domains with specific addons active, check the relevant Domain Addons checkboxes. This is useful for adjusting the price of the individual addons (for example, to increase the price of ID Protection, select the ID Protection checkbox).
  - The currency and current price are optional. If you run multiple currencies then you would need to do a separate update request for each currency, and if you have certain clients on older or special pricing, you can use the current price field to restrict a change to only users with a specific current price, thus allowing you to keep the users on different pricing.
  - The system will prompt you to provide either a New Price to assign matching items to, or an amount to Increase Existing Prices By. You should only ever specify one or the other of these (never both).
- Step 3 — Review — This step provides a summary of your criteria and the change that will be made and asks you to confirm everything is correct. Once you proceed, you can't undo the action, so be sure to check the proposed changes and criteria.
- Step 4 — Perform Update — The system will perform the update and the addon will tell you the number of items that the system adjusted. Upon completion of an update, if you find it didn't apply to as many items as you had expected, you can go back and refine your criteria further.

Change Tax Rate

Sometimes, governments change the sales tax rates. This is significant, since you must also update your rates accordingly.

For the purposes of this example the UK sales tax, VAT, is increasing from 17.5% to 20% on 4th January.

This means that at midnight on Monday, 3rd January, or at the latest before the cron job run on the 4th for generating new invoices, you will want to update the tax rules in your WHMCS installation so that new orders and invoices use the higher rate. This is possible through the WHMCS admin interface under Setup > Payments > Tax Configuration:

Delete the original tax rule by clicking the corresponding red delete icon.
Create a new tax rule with exactly the same country and state but enter the new tax rate.

Any invoices that the system generates after this change will use the new tax rate, but any existing invoices will keep the old tax rate.

If you have multiple separate rules this method can be time-consuming, so you can do this in bulk by running an SQL update query on your WHMCS database via a tool such as phpMyAdmin:

UPDATE tbltax SET taxrate=20 WHERE taxrate=17.5;

This won't affect existing invoices, and it will keep the 17.5% tax rates they had when the system generated them. This will just mean that for any invoices that the system generates after the change, use the new higher 20% tax rate.

If you also wish to update existing but unpaid invoices from before the 4th but due on or after it, then you can use this query to do that:

UPDATE tblinvoices SET taxrate=20,tax=subtotal*0.2,total=subtotal+tax-credit WHERE status='Unpaid'
AND taxrate=17.5 AND duedate>='2011-01-04';

Migrate Payment Gateways

Sometimes, you may want to stop using one payment gateway and switch to another. This is a general guide to the process:

Enable the new payment gateway module under Setup > Payments > Payment Gateways and configure it per our documentation.
Deactivate the old module by clicking Deactivate on the Payment Gateways page.
The system will prompt you to choose the payment gateway you wish to reassign all existing services and invoices to. Select the new payment gateway. For more information, see Deactivating Gateway Modules.
Depending upon the type of payment gateway module you're switching to, there may be a third step:
1. If you are switching between merchant gateways or third party gateway modules, there is no third step and you are finished.
2. If you are switching to a merchant gateway for the first time, the client will need to log in and enter their card details to the "My Details" page in the client area. The system will charge the card when the next invoice is due.
3. If you are switching between tokenisation modules, the client will need to log in and pay their first invoice manually, which will store their card details on your processor's servers. The system will attempt subsequent payments automatically. Regrettably, there isn't a way for the migration to be done without client's intervention because the system requires their CVV number for the first payment.
4. If you are switching from a merchant gateway to a tokenization gateway, typically clients will need to manually pay their next invoice via the client area. If you store card details or a token for the client, you may wish to delete them via the "Credit Card Information" link on each client's summary page beforehand. There are some exceptions, though, and some payment gateways have card number migration paths:
  - Stripe
5. If you are switching from a merchant or tokenization gateway to a third party gateway, clients will need to manually pay their next invoice via the client area. If you store card details or a token for the client, you may wish to delete them via the "Credit Card Information" link on each client's summary page beforehand.

Advanced Billing Scenarios

Watch the video tutorial for this feature

The above video tutorial shows and explains how to handle two advanced billing scenarios:

Change a billing cycle from annual to monthly, with the added complication that the system has already generated an annual renewal invoice.
Consolidate the renewal date of several services onto the same day on a single invoice in the future, even if the client has already renewed some services this month.

Switching Domain Registrars

Domain prices change frequently. If one finds a chosen registrar's price is no longer competitive, it may be desirable to transfer existing domains to a different registrar without the client's knowledge. WHMCS can make the process easier, saving the need to log in to both provider's control panels:

Navigate to Clients > Domain Registrations and select the domain in question.
Uncheck the Registrar Lock checkbox and click Save Changes.
Click the Modify Contact Details button.
Change the registrant email address to your own and click Save Changes.
Return to the client's Domains tab and click the Get EPP Code button.
Note the onscreen EPP Code.
Select the new domain registrar from the Registrar dropdown menu.
Click the Transfer Module Command button.

You should see a confirmation message stating the transfer initiated successfully. It is likely that the client's Domains tab will display an error message from the new registrar, but this will disappear once the transfer process is complete.

Note
Once the transfer process is complete, be sure to use the Modify Contact Details button to change the registrant email address back to the client's own address.

Convert invoice amounts into a different currency

It is possible that not every gateway you use will accept all the currencies you offer on your site. For those that don’t, WHMCS can transparently convert the payment amount into a different currency before sending the client to the payment gateway.

For example: Gateway A only operates in USD, but you have configured multi-currency in WHMCS, offering prices in USD, GBP and EUR. When a client places an order for 10GBP and chooses to pay via Gateway A, the system will automatically convert the amount to 15USD before the payment processes. The client is able to make payment via Gateway A where they otherwise would not be able to do so.

To configure this feature:

Navigate to Setup > Payments > Payment Gateways > Manage Existing Gateways.
Under the payment gateway in question, locate the Convert to For Processing setting.
From the menu, select your desired currency.
Click Save Changes.

To continue the example from above, one would choose the USD currency from the Gateway A section. The system will send all payments to this gateway in the chosen currency, regardless of which currency the client selected on the order form.

Note
The Convert to For Processing option will appear once you configure a second currency.

Note
The system performs the currency conversion using the Base Conversion Rate in your WHMCS installation at the time of payment.

Credit a client for money received

When you receive money from a client, you should record it in WHMCS as a transaction. But if the payment is not for a specific invoice or the client has accidentally overpaid, the client's credit balance should be increased accordingly. Adding credits via the "Manage Credits" popup would not appear on the transaction record as they are not transactions.

To credit a client and create a transaction:

Navigate to Billing > Transactions List > Add Transaction tab.
Enter the details of the credit.
Check the Credit checkbox.
Click Add Transaction.

This will ensure your accounting records are accurate and the Account Statement report is balanced.

Cancel and regenerate invoice

Sometimes, you may wish to cancel an unpaid invoice and later need to regenerate an invoice covering the same time period for the service.

To cancel the original invoice:

Navigate to Billing > Invoices.
Click on the invoice in question.
Click the "Marked Cancelled" button.

To regenerate the invoice for the same period:

Navigate to Clients > Products/Services.
Click on the service.
Move the Next Due Date forward by one day. This will ensure the "next invoice date" value in the database resets to match the next due date when using Continuous Invoicing.

Click Save Changes.
Navigate to the Client Summary page.
Click "Generate Due Invoices".

Skip an invoice

Occasionally you may wish to skip an invoice, giving the customer the invoiced period at no charge, but resume charging on the next due date.

If an unpaid invoice already exists:

Navigate to Billing > Invoices.
Click the invoice in question.
Click the "Mark Cancelled" button.

You can now set the Next Due Date for when charging should resume:

Navigate to the service that you wish to extend at no charge.
Set the the Next Due Date.
Click "Save Changes".

The system will create the next invoice on the new Next Due Date without charging for the period between the old next due date and the new next due date.