WHMCS Documentation - User contributions [en]

Cron Job Issues

2024-04-09T11:49:18Z

PeterM:

{{troubleshooting}}

You may encounter some common problems and errors that can occur when running the WHMCS cron job.

For more information about troubleshooting cron job issues, see [https://help.whmcs.com/m/automation/c/195647 our cron and automation troubleshooting guides].

==Troubleshooting==

There are several techniques available for troubleshooting the problems that you may encounter with the cron job:

===Cron Execution===

If you do not receive the daily cron digest email, see a warning on the System Health Status overview page, or on the Automation Status page then this indicates the cron not running. Troubleshooting and resolving this is a matter of priority, as the daily automation tasks are an integral part of WHMCS.

Detailed steps on how to debug the cron execution can be found in our [https://help.whmcs.com/m/automation/l/683269-advanced-cron-troubleshooting|Advanced Cron Troubleshooting] Guide.

===Run the cron job in your browser===

To do this:

# In the WHMCS admin area, go to the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
# Enable the '''Display Errors''' option.
# Visit the <tt>cron.php</tt> file in your browser. For example: <source lang="php">http://www.example.com/whmcs/crons/cron.php</source>

<div class="docs-alert-info">
<span class="title">Note</span><br />
Executing <tt>cron.php</tt> from a web browser is not possible if the <tt>/crons</tt> directory is not inside a web-accessible directory. It will be subject to limitations that apply to executing any PHP script via a web browser such as, timeouts and won't provide any output on screen to examine (the execution must be observed from the Activity Log). Where possible, executing <tt>cron.php</tt> from your server's command line interface is the recommended troubleshooting method.
</div>

===Run the cron job from the server command line===

To do this:

# Access your server's command line.
# Copy the cron job command for the <tt>cron.php</tt> file from your server's cron tab. <source lang="php">crontab -u userName -l</source> Where <tt>userName</tt> represents the user on the server for which the cron command is configured under.
# Execute the command you copied with the addition of the verbose option:<source lang="php">php -q /path/to/whmcs/crons/cron.php -vvv</source>
# Examine the output for any errors.
# To execute all daily automation tasks, adjust the cron command again to add in the force option:<source lang="php">php -q /path/to/whmcs/crons/cron.php --force -vvv</source> This should only ever be executed once in any 24 hour period. Do this with the explicit intention of identifying why the cron may not be completing successfully.

For more information, see [[Crons#Commands|Cron Commands.]]

===Run the cron job from the server command line with debugging enabled===

To do this:

* Make sure you have enabled '''Display Errors''' in the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
* Access your server's command line.
* Make sure you have enabled '''display_errors''' in your command line PHP environment: <source lang="php">php -i | grep display_errors
display_errors => STDOUT => STDOUT</source>
* Copy the cron job command for the <tt>cron.php</tt> file from your server's crontab: <source lang="php">crontab -u userName -l</source>
* Add the --force option to the end of the cron command and execute it:<source lang="php">php -q /path/to/whmcs/crons/cron.php all --force -vvv</source>
*Examine the output for any errors. The final line output should be "'''[OK] Completed'''".

==Common Errors==

===Site error: the file /path/to/crons/cron.php requires the ionCube PHP Loader ioncube_loader_lin_5.6.so to be installed by the website operator===

Seeing this error output indicates that the PHP configuration for your WHMCS installation may be different than the one on the command line.

Log in as the same user that the cron job runs under. Then, run the following command at the server's command line to see the version information for your PHP and ionCube Loader® configurations:

<source lang="php">
php -v
</source>

You should get an output along the lines of:

<source lang="php">
PHP 5.4.43 (cli) (built: Aug 2 2015 02:44:35)
Copyright (c) 1997-2014 The PHP Group
Zend Engine v2.4.0, Copyright (c) 1998-2014 Zend Technologies
with the ionCube PHP Loader v4.7.5, Copyright (c) 2002-2014, by ionCube Ltd.
</source>

If the <tt>with the ionCube PHP Loader</tt> line is absent, this indicates that ionCube Loader is not available for this user. Work with your hosting provider or server administrator to ensure that ionCube Loader is available to the cron job user.

===Unable to communicate with the WHMCS installation===

This error occurs when the <tt>cron.php</tt> file is unable to communicate with the WHMCS installation. This typically occurs when you are using a custom location for the <tt>/crons</tt> directory. The <tt>cron.php</tt> file will look for the WHMCS directory in the location that you specified in the <tt>/crons/config.php</tt> file. To resolve this error:

* Open the <tt>/crons/config.php</tt> file.
* Ensure the <tt>$whmcspath</tt> line is uncommented by removing the preceding <tt>//</tt> characters.
* Ensure the <tt>$whmcspath</tt> path is the full system path to your WHMCS directory. This is the directory that contains the <tt>init.php</tt> and <tt>clientarea.php</tt> files.

When you finish, the entire file will look like this:

<source lang="php">
<?php
/**
* Custom Crons Directory Configuration
*
* This crons folder may be moved to any place above or below the docroot.
*
* We recommend locating it outside the docroot to prevent browser based access.
*
* Upon moving it, you must provide the path to your WHMCS installation to
* allow the cron task files to communicate with the parent WHMCS installation.
*
* To do this, rename this file config.php, then uncomment and enter the full
* path to the WHMCS root directory in the $whmcspath variable below.
*
* You must also provide the appropriate path to the crons folder in the
* $crons_dir variable inside the WHMCS master configuration file.
*
* For more information please see http://docs.whmcs.com/Custom_Crons_Directory
*/

$whmcspath = '/home/username/public_html/whmcs/';
</source>

===Could not open input file: /path/to/crons/cron.php ===

This error occurs when the <tt>cron.php</tt> file is not present in specified directory path. Check the path and correct it, or ensure the <tt>cron.php</tt> file is present.

===Oops! Something went wrong and we couldn't process your request===

This indicates that a fatal PHP error has occurred. Go to the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. Select 'Display Errors'. Then, run the cron job again. The system will display the full error. The error normally indicates an issue with one or more modules.

For example, you could see:

<source lang="php">
<p class="debug">exception 'Whoops\Exception\ErrorException' with message 'Cannot redeclare class module_class' in /home/whmcs/public_html/modules/gateways/module-name/module-file.php:16<br />
</source>

If the error references a third party module you are using, you will need to contact the developers of the module to review and resolve the error. If the error references a WHMCS-developed and shipped module, contact our Support Team. It may also indicate an issue with the PHP configuration. For more information, see the sections below.

===Fatal error: Allowed memory size of 33554432 bytes exhausted (tried to allocate 20480 bytes)===

This error indicates that the system is terminating the cron job because it has exceeded the 'memory_limit' value of 32 MB. Increase this to 64 MB (128 MB if possible) to resolve this. Contact your server administrator or hosting provider for assistance with this.

You can check the limit using this command:

<source lang="php">
php -ini | grep "memory_limit"
</source>

You can also set the memory limit (<tt>memory_limit</tt>) directly in the cron command. For example:
<source lang="php">
php -d memory_limit=128M -q /path/to/whmcs/crons/cron.php
</source>

===The file /path/to/crons/cron.php is corrupted===

You may see this error in version 7.5 and above. This error will occur if you are running ionCube Loader 10.0 or earlier. WHMCS 7.5 requires ionCube Loader 10.1.0 or above. If your WHMCS installation is working, it indicates that the PHP configuration for your WHMCS installation may be different than the one that you use on the command line. To check this, you can again use the command below:

<source lang="php">
php -v
</source>

Look for the following line to identify the ionCube Loader version:

<source lang="php">
with the ionCube PHP Loader (enabled) + Intrusion Protection from ioncube24.com (unconfigured) v10.2.0, Copyright
(c) 2002-2018, by ionCube Ltd.
</source>

===Error: Call to undefined function curl_init()===

This error indicates that the system is terminating the cron job because the 'curl' extension is missing. To check this, run the following command:

<source lang="php">
php -m
</source>

A similar error may also occur if the 'curl_init' function is a disabled function in your PHP configuration.

===Whoops\Exception\ErrorException' with message 'Maximum execution time of 30 seconds exceeded===

This error indicates that the system is terminating the cron job because it has exceeded the 'max_execution_limit' value of 30 seconds. Increase this to an appropriate value for the size of your installation. For most servers, a limit of '120' is sufficient, but larger servers may need a value of '300'.

You can check the limit using this command:
<source lang="php">php -ini | grep "max_execution_time"</source>

You can also set the <tt>max_execution_time</tt> value directly in the cron command. For example:
<source lang="php">
php -d max_execution_time=300 -q /path/to/whmcs/crons/cron.php
</source>

===The cron is using a different timezone===

If your cron job is using a different timezone than your website's, you can change the timezone (<tt>date.timezone</tt>) directly in the cron command:
<source lang="php">
php -d date.timezone="Europe/London" -q /path/to/whmcs/crons/cron.php
</source>

===Segmentation fault===

This error is not directly related to the WHMCS software and can occur for many different reasons. It most commonly indicates that PHP is crashing and suggests there is an issue with your PHP installation (for example, a malfunctioning extension). It is something your server administrator or hosting provider would need to investigate, possibly using the 'strace' utility.

===Domain renew link in emails is broken===

Under some PHP server configurations, the system generates the URL for the domain renewal link in domain renewal reminder emails incorrectly.

You can usually fix this by using the correct PHP binary on your cron job. Alternatively, you can adjust the cron job to work around the issue by formatting your cron command, as in the following example:

<source lang="php">
cd /path/to/crons/ && php -q cron.php
</source>

===Could not connect to database===

This error occurs when the <tt>cron.php</tt> script cannot access your MySQL® database. This is often because the PHP configuration that the <tt>cron.php</tt> script runs under is missing one or all of the following extensions:

* PDO
* PDO MySQL
* MySQLi

It can also be the result of a jailed environment with strict limitations. Your system administrator or hosting provider can check for the required extensions and any environmental limitations by testing a connection to the database and resolving any issues.

{{troubleshooting}}

Cron Job Issues

2024-04-09T11:48:08Z

PeterM: /* Whoops\Exception\ErrorException' with message 'Maximum execution time of 30 seconds exceeded */

{{troubleshooting}}

You may encounter some common problems and errors that can occur when running the WHMCS cron job.

For more information about troubleshooting cron job issues, see [https://help.whmcs.com/m/automation/c/195647 our cron and automation troubleshooting guides].

==Troubleshooting==

There are several techniques available for troubleshooting the problems that you may encounter with the cron job:

===Cron Execution===

If you do not receive the daily cron digest email, see a warning on the System Health Status overview page, or on the Automation Status page then this indicates the cron not running. Troubleshooting and resolving this is a matter of priority, as the daily automation tasks are an integral part of WHMCS.

Detailed steps on how to debug the cron execution can be found in our [https://help.whmcs.com/m/automation/l/683269-advanced-cron-troubleshooting|Advanced Cron Troubleshooting] Guide.

===Run the cron job in your browser===

To do this:

# In the WHMCS admin area, go to the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
# Enable the '''Display Errors''' option.
# Visit the <tt>cron.php</tt> file in your browser. For example: <source lang="php">http://www.example.com/whmcs/crons/cron.php</source>

<div class="docs-alert-info">
<span class="title">Note</span><br />
Executing <tt>cron.php</tt> from a web browser is not possible if the <tt>/crons</tt> directory is not inside a web-accessible directory. It will be subject to limitations that apply to executing any PHP script via a web browser such as, timeouts and won't provide any output on screen to examine (the execution must be observed from the Activity Log). Where possible, executing <tt>cron.php</tt> from your server's command line interface is the recommended troubleshooting method.
</div>

===Run the cron job from the server command line===

To do this:

# Access your server's command line.
# Copy the cron job command for the <tt>cron.php</tt> file from your server's cron tab. <source lang="php">crontab -u userName -l</source> Where <tt>userName</tt> represents the user on the server for which the cron command is configured under.
# Execute the command you copied with the addition of the verbose option:<source lang="php">php -q /path/to/whmcs/crons/cron.php -vvv</source>
# Examine the output for any errors.
# To execute all daily automation tasks, adjust the cron command again to add in the force option:<source lang="php">php -q /path/to/whmcs/crons/cron.php --force -vvv</source> This should only ever be executed once in any 24 hour period. Do this with the explicit intention of identifying why the cron may not be completing successfully.

For more information, see [[Crons#Commands|Cron Commands.]]

===Run the cron job from the server command line with debugging enabled===

To do this:

* Make sure you have enabled '''Display Errors''' in the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
* Access your server's command line.
* Make sure you have enabled '''display_errors''' in your command line PHP environment: <source lang="php">php -i | grep display_errors
display_errors => STDOUT => STDOUT</source>
* Copy the cron job command for the <tt>cron.php</tt> file from your server's crontab: <source lang="php">crontab -u userName -l</source>
* Add the --force option to the end of the cron command and execute it:<source lang="php">php -q /path/to/whmcs/crons/cron.php all --force -vvv</source>
*Examine the output for any errors. The final line output should be "'''[OK] Completed'''".

==Common Errors==

===Site error: the file /path/to/crons/cron.php requires the ionCube PHP Loader ioncube_loader_lin_5.6.so to be installed by the website operator===

Seeing this error output indicates that the PHP configuration for your WHMCS installation may be different than the one on the command line.

Log in as the same user that the cron job runs under. Then, run the following command at the server's command line to see the version information for your PHP and ionCube Loader® configurations:

<source lang="php">
php -v
</source>

You should get an output along the lines of:

<source lang="php">
PHP 5.4.43 (cli) (built: Aug 2 2015 02:44:35)
Copyright (c) 1997-2014 The PHP Group
Zend Engine v2.4.0, Copyright (c) 1998-2014 Zend Technologies
with the ionCube PHP Loader v4.7.5, Copyright (c) 2002-2014, by ionCube Ltd.
</source>

If the <tt>with the ionCube PHP Loader</tt> line is absent, this indicates that ionCube Loader is not available for this user. Work with your hosting provider or server administrator to ensure that ionCube Loader is available to the cron job user.

===Unable to communicate with the WHMCS installation===

This error occurs when the <tt>cron.php</tt> file is unable to communicate with the WHMCS installation. This typically occurs when you are using a custom location for the <tt>/crons</tt> directory. The <tt>cron.php</tt> file will look for the WHMCS directory in the location that you specified in the <tt>/crons/config.php</tt> file. To resolve this error:

* Open the <tt>/crons/config.php</tt> file.
* Ensure the <tt>$whmcspath</tt> line is uncommented by removing the preceding <tt>//</tt> characters.
* Ensure the <tt>$whmcspath</tt> path is the full system path to your WHMCS directory. This is the directory that contains the <tt>init.php</tt> and <tt>clientarea.php</tt> files.

When you finish, the entire file will look like this:

<source lang="php">
<?php
/**
* Custom Crons Directory Configuration
*
* This crons folder may be moved to any place above or below the docroot.
*
* We recommend locating it outside the docroot to prevent browser based access.
*
* Upon moving it, you must provide the path to your WHMCS installation to
* allow the cron task files to communicate with the parent WHMCS installation.
*
* To do this, rename this file config.php, then uncomment and enter the full
* path to the WHMCS root directory in the $whmcspath variable below.
*
* You must also provide the appropriate path to the crons folder in the
* $crons_dir variable inside the WHMCS master configuration file.
*
* For more information please see http://docs.whmcs.com/Custom_Crons_Directory
*/

$whmcspath = '/home/username/public_html/whmcs/';
</source>

===Could not open input file: /path/to/crons/cron.php ===

This error occurs when the <tt>cron.php</tt> file is not present in specified directory path. Check the path and correct it, or ensure the <tt>cron.php</tt> file is present.

===Oops! Something went wrong and we couldn't process your request===

This indicates that a fatal PHP error has occurred. Go to the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. Select 'Display Errors'. Then, run the cron job again. The system will display the full error. The error normally indicates an issue with one or more modules.

For example, you could see:

<source lang="php">
<p class="debug">exception 'Whoops\Exception\ErrorException' with message 'Cannot redeclare class module_class' in /home/whmcs/public_html/modules/gateways/module-name/module-file.php:16<br />
</source>

If the error references a third party module you are using, you will need to contact the developers of the module to review and resolve the error. If the error references a WHMCS-developed and shipped module, contact our Support Team. It may also indicate an issue with the PHP configuration. For more information, see the sections below.

===Fatal error: Allowed memory size of 33554432 bytes exhausted (tried to allocate 20480 bytes)===

This error indicates that the system is terminating the cron job because it has exceeded the 'memory_limit' value of 32 MB. Increase this to 64 MB (128 MB if possible) to resolve this. Contact your server administrator or hosting provider for assistance with this.

You can check the limit using this command:

<source lang="php">
php -ini | grep "memory_limit"
</source>

You can also set the memory limit (<tt>memory_limit</tt>) directly in the cron command. For example:
<source lang="php">
php -d memory_limit=128M -q /path/to/whmcs/crons/cron.php
</source>

===The file /path/to/crons/cron.php is corrupted===

You may see this error in version 7.5 and above. This error will occur if you are running ionCube Loader 10.0 or earlier. WHMCS 7.5 requires ionCube Loader 10.1.0 or above. If your WHMCS installation is working, it indicates that the PHP configuration for your WHMCS installation may be different than the one that you use on the command line. To check this, you can again use the command below:

<source lang="php">
php -v
</source>

Look for the following line to identify the ionCube Loader version:

<source lang="php">
with the ionCube PHP Loader (enabled) + Intrusion Protection from ioncube24.com (unconfigured) v10.2.0, Copyright
(c) 2002-2018, by ionCube Ltd.
</source>

===Error: Call to undefined function curl_init()===

This error indicates that the system is terminating the cron job because the 'curl' extension is missing. To check this, run the following command:

<source lang="php">
php -m
</source>

A similar error may also occur if the 'curl_init' function is a disabled function in your PHP configuration.

===Whoops\Exception\ErrorException' with message 'Maximum execution time of 30 seconds exceeded===

This error indicates that the system is terminating the cron job because it has exceeded the 'max_execution_limit' value of 30 seconds. Increase this to an appropriate value for the size of your installation. For most servers, a limit of '120' is sufficient, but larger servers may need a value of '300'.

You can check the limit using this command:
<source lang="php">php -ini | grep "max_execution_time"</source>

You can also set the <tt>max_execution_time</tt> value directly in the cron command. For example:
<source lang="php">
php -d max_execution_time=300 -q /path/to/whmcs/crons/cron.php
</source>

===Segmentation fault===

This error is not directly related to the WHMCS software and can occur for many different reasons. It most commonly indicates that PHP is crashing and suggests there is an issue with your PHP installation (for example, a malfunctioning extension). It is something your server administrator or hosting provider would need to investigate, possibly using the 'strace' utility.

===Domain renew link in emails is broken===

Under some PHP server configurations, the system generates the URL for the domain renewal link in domain renewal reminder emails incorrectly.

You can usually fix this by using the correct PHP binary on your cron job. Alternatively, you can adjust the cron job to work around the issue by formatting your cron command, as in the following example:

<source lang="php">
cd /path/to/crons/ && php -q cron.php
</source>

===Could not connect to database===

This error occurs when the <tt>cron.php</tt> script cannot access your MySQL® database. This is often because the PHP configuration that the <tt>cron.php</tt> script runs under is missing one or all of the following extensions:

* PDO
* PDO MySQL
* MySQLi

It can also be the result of a jailed environment with strict limitations. Your system administrator or hosting provider can check for the required extensions and any environmental limitations by testing a connection to the database and resolving any issues.

{{troubleshooting}}

Cron Job Issues

2024-04-09T11:47:25Z

PeterM: /* Fatal error: Allowed memory size of 33554432 bytes exhausted (tried to allocate 20480 bytes) */

{{troubleshooting}}

You may encounter some common problems and errors that can occur when running the WHMCS cron job.

For more information about troubleshooting cron job issues, see [https://help.whmcs.com/m/automation/c/195647 our cron and automation troubleshooting guides].

==Troubleshooting==

There are several techniques available for troubleshooting the problems that you may encounter with the cron job:

===Cron Execution===

If you do not receive the daily cron digest email, see a warning on the System Health Status overview page, or on the Automation Status page then this indicates the cron not running. Troubleshooting and resolving this is a matter of priority, as the daily automation tasks are an integral part of WHMCS.

Detailed steps on how to debug the cron execution can be found in our [https://help.whmcs.com/m/automation/l/683269-advanced-cron-troubleshooting|Advanced Cron Troubleshooting] Guide.

===Run the cron job in your browser===

To do this:

# In the WHMCS admin area, go to the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
# Enable the '''Display Errors''' option.
# Visit the <tt>cron.php</tt> file in your browser. For example: <source lang="php">http://www.example.com/whmcs/crons/cron.php</source>

<div class="docs-alert-info">
<span class="title">Note</span><br />
Executing <tt>cron.php</tt> from a web browser is not possible if the <tt>/crons</tt> directory is not inside a web-accessible directory. It will be subject to limitations that apply to executing any PHP script via a web browser such as, timeouts and won't provide any output on screen to examine (the execution must be observed from the Activity Log). Where possible, executing <tt>cron.php</tt> from your server's command line interface is the recommended troubleshooting method.
</div>

===Run the cron job from the server command line===

To do this:

# Access your server's command line.
# Copy the cron job command for the <tt>cron.php</tt> file from your server's cron tab. <source lang="php">crontab -u userName -l</source> Where <tt>userName</tt> represents the user on the server for which the cron command is configured under.
# Execute the command you copied with the addition of the verbose option:<source lang="php">php -q /path/to/whmcs/crons/cron.php -vvv</source>
# Examine the output for any errors.
# To execute all daily automation tasks, adjust the cron command again to add in the force option:<source lang="php">php -q /path/to/whmcs/crons/cron.php --force -vvv</source> This should only ever be executed once in any 24 hour period. Do this with the explicit intention of identifying why the cron may not be completing successfully.

For more information, see [[Crons#Commands|Cron Commands.]]

===Run the cron job from the server command line with debugging enabled===

To do this:

* Make sure you have enabled '''Display Errors''' in the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
* Access your server's command line.
* Make sure you have enabled '''display_errors''' in your command line PHP environment: <source lang="php">php -i | grep display_errors
display_errors => STDOUT => STDOUT</source>
* Copy the cron job command for the <tt>cron.php</tt> file from your server's crontab: <source lang="php">crontab -u userName -l</source>
* Add the --force option to the end of the cron command and execute it:<source lang="php">php -q /path/to/whmcs/crons/cron.php all --force -vvv</source>
*Examine the output for any errors. The final line output should be "'''[OK] Completed'''".

==Common Errors==

===Site error: the file /path/to/crons/cron.php requires the ionCube PHP Loader ioncube_loader_lin_5.6.so to be installed by the website operator===

Seeing this error output indicates that the PHP configuration for your WHMCS installation may be different than the one on the command line.

Log in as the same user that the cron job runs under. Then, run the following command at the server's command line to see the version information for your PHP and ionCube Loader® configurations:

<source lang="php">
php -v
</source>

You should get an output along the lines of:

<source lang="php">
PHP 5.4.43 (cli) (built: Aug 2 2015 02:44:35)
Copyright (c) 1997-2014 The PHP Group
Zend Engine v2.4.0, Copyright (c) 1998-2014 Zend Technologies
with the ionCube PHP Loader v4.7.5, Copyright (c) 2002-2014, by ionCube Ltd.
</source>

If the <tt>with the ionCube PHP Loader</tt> line is absent, this indicates that ionCube Loader is not available for this user. Work with your hosting provider or server administrator to ensure that ionCube Loader is available to the cron job user.

===Unable to communicate with the WHMCS installation===

This error occurs when the <tt>cron.php</tt> file is unable to communicate with the WHMCS installation. This typically occurs when you are using a custom location for the <tt>/crons</tt> directory. The <tt>cron.php</tt> file will look for the WHMCS directory in the location that you specified in the <tt>/crons/config.php</tt> file. To resolve this error:

* Open the <tt>/crons/config.php</tt> file.
* Ensure the <tt>$whmcspath</tt> line is uncommented by removing the preceding <tt>//</tt> characters.
* Ensure the <tt>$whmcspath</tt> path is the full system path to your WHMCS directory. This is the directory that contains the <tt>init.php</tt> and <tt>clientarea.php</tt> files.

When you finish, the entire file will look like this:

<source lang="php">
<?php
/**
* Custom Crons Directory Configuration
*
* This crons folder may be moved to any place above or below the docroot.
*
* We recommend locating it outside the docroot to prevent browser based access.
*
* Upon moving it, you must provide the path to your WHMCS installation to
* allow the cron task files to communicate with the parent WHMCS installation.
*
* To do this, rename this file config.php, then uncomment and enter the full
* path to the WHMCS root directory in the $whmcspath variable below.
*
* You must also provide the appropriate path to the crons folder in the
* $crons_dir variable inside the WHMCS master configuration file.
*
* For more information please see http://docs.whmcs.com/Custom_Crons_Directory
*/

$whmcspath = '/home/username/public_html/whmcs/';
</source>

===Could not open input file: /path/to/crons/cron.php ===

This error occurs when the <tt>cron.php</tt> file is not present in specified directory path. Check the path and correct it, or ensure the <tt>cron.php</tt> file is present.

===Oops! Something went wrong and we couldn't process your request===

This indicates that a fatal PHP error has occurred. Go to the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. Select 'Display Errors'. Then, run the cron job again. The system will display the full error. The error normally indicates an issue with one or more modules.

For example, you could see:

<source lang="php">
<p class="debug">exception 'Whoops\Exception\ErrorException' with message 'Cannot redeclare class module_class' in /home/whmcs/public_html/modules/gateways/module-name/module-file.php:16<br />
</source>

If the error references a third party module you are using, you will need to contact the developers of the module to review and resolve the error. If the error references a WHMCS-developed and shipped module, contact our Support Team. It may also indicate an issue with the PHP configuration. For more information, see the sections below.

===Fatal error: Allowed memory size of 33554432 bytes exhausted (tried to allocate 20480 bytes)===

This error indicates that the system is terminating the cron job because it has exceeded the 'memory_limit' value of 32 MB. Increase this to 64 MB (128 MB if possible) to resolve this. Contact your server administrator or hosting provider for assistance with this.

You can check the limit using this command:

<source lang="php">
php -ini | grep "memory_limit"
</source>

You can also set the memory limit (<tt>memory_limit</tt>) directly in the cron command. For example:
<source lang="php">
php -d memory_limit=128M -q /path/to/whmcs/crons/cron.php
</source>

===The file /path/to/crons/cron.php is corrupted===

You may see this error in version 7.5 and above. This error will occur if you are running ionCube Loader 10.0 or earlier. WHMCS 7.5 requires ionCube Loader 10.1.0 or above. If your WHMCS installation is working, it indicates that the PHP configuration for your WHMCS installation may be different than the one that you use on the command line. To check this, you can again use the command below:

<source lang="php">
php -v
</source>

Look for the following line to identify the ionCube Loader version:

<source lang="php">
with the ionCube PHP Loader (enabled) + Intrusion Protection from ioncube24.com (unconfigured) v10.2.0, Copyright
(c) 2002-2018, by ionCube Ltd.
</source>

===Error: Call to undefined function curl_init()===

This error indicates that the system is terminating the cron job because the 'curl' extension is missing. To check this, run the following command:

<source lang="php">
php -m
</source>

A similar error may also occur if the 'curl_init' function is a disabled function in your PHP configuration.

===Whoops\Exception\ErrorException' with message 'Maximum execution time of 30 seconds exceeded===

This error indicates that the system is terminating the cron job because it has exceeded the 'max_execution_limit' value of 30 seconds. Increase this to an appropriate value for the size of your installation. For most servers, a limit of '120' is sufficient, but larger servers may need a value of '300'.

You can check the limit using this command:
<source lang="php">php -ini | grep "max_execution_time"</source>

===Segmentation fault===

This error is not directly related to the WHMCS software and can occur for many different reasons. It most commonly indicates that PHP is crashing and suggests there is an issue with your PHP installation (for example, a malfunctioning extension). It is something your server administrator or hosting provider would need to investigate, possibly using the 'strace' utility.

===Domain renew link in emails is broken===

Under some PHP server configurations, the system generates the URL for the domain renewal link in domain renewal reminder emails incorrectly.

You can usually fix this by using the correct PHP binary on your cron job. Alternatively, you can adjust the cron job to work around the issue by formatting your cron command, as in the following example:

<source lang="php">
cd /path/to/crons/ && php -q cron.php
</source>

===Could not connect to database===

This error occurs when the <tt>cron.php</tt> script cannot access your MySQL® database. This is often because the PHP configuration that the <tt>cron.php</tt> script runs under is missing one or all of the following extensions:

* PDO
* PDO MySQL
* MySQLi

It can also be the result of a jailed environment with strict limitations. Your system administrator or hosting provider can check for the required extensions and any environmental limitations by testing a connection to the database and resolving any issues.

{{troubleshooting}}

PayPal Card Payments

2024-04-05T14:01:13Z

PeterM:

== About this Module ==

<div class="docs-alert-success">
We added this payment gateway in WHMCS 8.9 and '''strongly''' recommend '''[[PayPal Payments]]''' and '''PayPal Card Payments''' for '''all''' new PayPal® merchants.
</div>

<div class="docs-alert-warning">
If you enabled the '''PayPal Payments''' modules while using the Beta release of WHMCS 8.9, you '''must''' relink the associated PayPal accounts after you upgrade to the Release Candidate version of WHMCS 8.9 or later. If you do not do this, you may experience problems.
</div>

'''PayPal Card Payments''' augments the functionality of the '''[[PayPal Payments]]''' module and uses its linked PayPal accounts. When you activate '''[[PayPal Payments]]''', WHMCS also automatically activates '''PayPal Card Payments'''. This module allows you to display an unbranded option for credit and debit card payments that is visually separate from the PayPal checkout experience.
{{gateways
| type = token
| onetime = yes
| recurring = yes
| refunds = yes
| reversals = yes
| updatecc = yes
| deletecc = yes
| 3dsecure = yes
}}
<div class="docs-alert-info">This module supports 3D Secure for newly-entered cards and processing of vaulted (stored) cards.</div>

== Adding the PayPal Card Payments Payment Gateway ==

To set up the PayPal Card Payments payment gateway in WHMCS:

# Activate and configure the '''[[PayPal Payments]]''' module. <div class="docs-alert-success">This will also activate '''[[PayPal Card Payments]]'''.</div>
# Find the '''PayPal Card Payments''' module in the list of active gateways at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]'''. By default, '''PayPal Card Payments''' uses <tt>Credit/Debit Card</tt> as the Client Area display name.
# Check '''Show on Order Form''' to display this payment option in the Client Area during checkout.<div class="docs-alert-info">You cannot enable '''Show on Order Form''' for this module without first enabling '''Show on Order Form''' for the '''PayPal Payments''' module.</div>
# Click '''Save Changes'''.

== Using PayPal Card Payments ==

The '''PayPal Card Payments''' module augments the '''[[PayPal Payments]]''' module and uses its configuration. For more information on module functionality, see [[PayPal Payments]].

== Vaulting ==

In PayPal-supported countries, the '''PayPal Payments''' and '''PayPal Card Payments''' modules ensure the security of your customers’ stored payment details with merchant-level vaulting through PayPal Vault. When clients pay using '''PayPal Card Payments''', a '''Save card for faster checkout in future''' option will display while entering credit card details.

* Selecting this option causes PayPal to attempt to add the card to PayPal Vault.
* This option is '''not''' available in the Admin Area.

After PayPal successfully stores a payment method, it will be available for the client when they pay an invoice manually.

<div class="docs-alert-success">
If PayPal does not support PayPal Vault for your country or region, you can still use '''PayPal Card Payments''' for one-time payments. However, your clients will '''not''' be able to store their payment method.
</div>

<div class="docs-alert-info">For more information, see [[PayPal_Payments#Vaulting|Vaulting]].</div>

== Disputes ==

You can manage disputes for this module from within WHMCS at '''Billing > [[Disputes]]'''.

== Payment Gateway Balances ==

You can view your PayPal merchant account balance directly within the WHMCS Admin Area at '''Billing > [[Transactions]]'''.

<div class="docs-alert-info">For more information, see [[Payment Gateways]].</div>

PayPal Payments

2024-04-05T14:00:06Z

PeterM:

== About this Module ==

<div class="docs-alert-success">
We added this payment gateway in WHMCS 8.9 and '''strongly''' recommend it for '''all''' new PayPal® merchants.
</div>

<div class="docs-alert-warning">If you enabled this module while using the Beta release of WHMCS 8.9, you '''must''' reactivate the module before using it with WHMCS 8.9 Release Candidate or later. If you do not do this, you may experience problems with some payment methods.</div>

'''PayPal Payments''' uses PayPal’s latest secure tokenization system. It ensures the security of your customers’ stored payment details with merchant-level vaulting through PayPal Vault, now available for PayPal merchant accounts in [[#Vaulting|PayPal-supported countries]].

When you use '''PayPal Payments''', clients can make one-click payments, including payment with credit and debit cards, during checkout and on invoices. Activating '''PayPal Payments''' also activates the '''[[PayPal Card Payments]]''' module, giving you the choice to display a separate unbranded option that accepts credit and debit cards using PayPal Advanced Checkout.
{{gateways
| type = token
| onetime = yes
| recurring = yes
| refunds = yes
| reversals = yes
| deletecc = yes
| 3dsecure = yes
}}

== Adding the PayPal Payments Payment Gateway ==

To set up the '''PayPal Payments''' payment gateway in WHMCS:

# Ensure that your WHMCS installation uses an HTTPS-secured connection with a valid [https://www.whmcs.com/ssl-certificates SSL certificate]. If it does not, this module will not function correctly.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
# Choose the '''Payments''' category.
# Click '''Activate & Configure''' for '''PayPal Payments'''.<div class="docs-alert-success">This will also activate '''[[PayPal Card Payments]]'''.</div>
# Click '''Link PayPal Account''' to begin accepting payments with PayPal. <div class="docs-alert-info">To configure a PayPal Sandbox account for testing purposes, see [[#Test_Mode|Test Mode]] below.</div>
# Log in to your chosen PayPal account or sign up for a new one. API credentials will populate, WHMCS will save them automatically, and the page will refresh.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.<div class="docs-alert-info">You '''cannot''' disable '''Show on Order Form''' for '''PayPal Payments''' if '''Show on Order Form''' is enabled for '''[[PayPal Card Payments]]'''.</div>
# Optionally, enter a new display name for '''Display Name'''.
#* By default, this module uses <tt>PayPal</tt> as the Client Area display name.
#* You will see the name that you enter here when you configure the payment gateway at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]'''.
# Uncheck '''Test Mode'''. <div class="docs-alert-success">We enable '''[[#Test_Mode|Test Mode]]''' by default for this payment gateway.</div>
# Click '''Save Changes'''.

For a step-by-step walkthrough of the setup process, see [https://help.whmcs.com/m/payments/l/1782848-start-using-paypal-payments Start Using PayPal Payments].

=== Test Mode ===

You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful for testing your configuration. Using test mode requires linking a separate PayPal Sandbox account to your WHMCS installation in addition to your live PayPal merchant account.

To do this:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]'''.
# Find the '''PayPal Payments''' module and click '''Link Sandbox Account'''.
# Log in to your existing PayPal sandbox account or create a new PayPal sandbox account.
# Confirm permission for the WHMCS application to access your account.
# Click '''Confirm''' to continue. API credentials will populate and WHMCS will save them automatically.
# Check '''Test Mode'''.
# Click '''Save Changes'''.

=== PayPal Card Payments ===

When you activate '''PayPal Payments''', WHMCS also automatically activates '''[[PayPal Card Payments]]'''. This module augments '''PayPal Payments''', allowing you an unbranded option for credit and debit card payments that is visually separate from the PayPal checkout experience.

* This module uses the PayPal account settings that you configure for the '''PayPal Payments''' module.
* You '''cannot''' display the unbranded credit and debit card options that '''PayPal Card Payments''' offers on your order form without also displaying the PayPal option from the '''PayPal Payments''' module.

To set up the PayPal Card Payments payment gateway in WHMCS:

# Activate and configure the '''PayPal Payments''' module (above).
# Find the '''PayPal Card Payments''' module in the list of active gateways. By default, this module uses <tt>Credit/Debit Cards</tt> as the display name here and in the Client Area.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.<div class="docs-alert-info">You cannot enable '''Show on Order Form''' for this module without first enabling '''Show on Order Form''' for the '''PayPal Payments''' module.</div>
# Click '''Save Changes'''.

== Vaulting ==

In PayPal-supported countries, the '''PayPal Payments''' and '''PayPal Card Payments''' modules ensure the security of your customers’ stored payment details with merchant-level vaulting through PayPal Vault.

* When clients pay using '''PayPal Payments''', PayPal will attempt to store the pay method automatically.
* When clients pay using '''PayPal Card Payments''', a '''Save card for faster checkout in future''' option will display while entering credit card details.
** Selecting this option causes PayPal to attempt to add the card to PayPal Vault.
** This option is '''not''' available in the Admin Area.
* Unlike previous PayPal payment gateways, this module stores encrypted vaulted data locally.

After PayPal successfully stores a payment method, it will be available for the client when they pay an invoice manually.

<div class="docs-alert-info">
If PayPal does not support PayPal Vault for your country or region, you can still use these payment gateways for one-time payments. However, your clients will '''not''' be able to store their payment method.
</div>

=== Supported Merchant Countries ===

PayPal currently enables PayPal Vault for merchants in the United States, Canada, the United Kingdom, Australia, and the following EU countries:

Belgium, Bulgaria, The Republic of Cyprus, Czech Republic, Germany, Denmark, Estonia, Spain, Finland, France, Greece, Hungary, Italy, Lithuania, Luxembourg, Latvia, Malta, Netherland, Poland, Portugal, Romania, Sweden, Slovenia, and Slovakia.

== Unlink PayPal Account ==

<div class="docs-alert-warning">Unlinking your account prevents WHMCS from interacting with PayPal.</div>

Click '''Unlink PayPal Account''' to irreversibly remove the link to your PayPal account for both modules.

== Refresh PayPal Account ==

If a PayPal feature is unavailable or an error occurs, a '''Refresh PayPal Account''' option will display, allowing you to check your PayPal account’s status. You may wish to do this if, for example, you or PayPal have made changes to your merchant account.

The system will check:

* Whether you are able to receive payments to your linked PayPal accounts
* Whether you have verified your email address.
* Your access to PayPal features like PayPal Vault.

A checkmark in the displayed results indicates that you are in good standing and able to receive payments ('''Payments Receivable'''), your email is verified ('''Email Verified'''), or you can use a specific PayPal feature.

If the system detects problems, it instead displays a warning icon and, if applicable, logs the error to the '''Activity Log''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Logs'''.

== Disputes ==

You can manage disputes for this module from within WHMCS at '''Billing > [[Disputes]]'''.

== Payment Gateway Balances ==

You can view your PayPal merchant account balance directly within the WHMCS Admin Area at '''Billing > [[Transactions]]'''. You can view balances in the transaction list and in the transaction details for individual transactions.

== Troubleshooting ==

If your WHMCS installation’s URL has changed because you moved it, you must update the webhook URL in PayPal.

You can find information about most other payment gateway-related errors in the logs at '''Billing > Gateway Log''' and in the '''Module Log'''.

=== Updating the PayPal Webhook URL ===

If your WHMCS installation's URL has changed because you moved it, you must update the webhook URL in PayPal. This will allow WHMCS to continue to record transactions.

To update the PayPal webhook URL:

# Log in to [https://developer.paypal.com/developer/applications the PayPal developer portal].
# Click '''Live''', which will then display the WHMCS app.
# Click on the app name.
# Scroll to the '''Live Webhooks''' section and click the edit (pencil) icon.
# Update '''Webhook URL''' to the correct address, ending with <tt>/modules/gateways/callback/paypal_ppcpv.php</tt>.
# Click '''Save'''.

Automation Settings

2024-02-23T18:55:41Z

PeterM:

The '''Automation Settings''' allow you to configure all of WHMCS's automated processes. This includes suspensions, unsuspensions, terminations, how far in advance the system generates invoices, and when the system sends overdue notices. It's the one central place that controls everything that the daily automation tasks do.

You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Automation Settings''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''.

To trigger the daily automation tasks, you must configure a [[Crons|Cron Job]] at a recommended frequency of every 5 minutes. This is usually part of the initial installation of WHMCS.

[[File:Videotutorial.png‎|center|link=https://www.youtube.com/watch?v=Yk3-Ud0jITc&list=PLfpgUwyOgC7C4wwPhB7jEqSp_esXB31Jb&index=5&t=0s|Watch Video Tutorial]]

==Scheduling==

===Time of Day===
[[File:Time of Day.png|thumb|Time of Day]]
This setting allows you to select the hour in which you'd like WHMCS to perform all daily automation tasks. To function properly, this setting depends on configuring your cron job to run at least once every hour. We recommend setting it to run every 5 minutes to allow other system processes, such as checking for updates, to take place.

==Automatic Module Functions==
[[File:Automatic Module Functions.png|thumb|Automatic Module Functions]]
These settings pertain to your customer’s products or services and how the system handles non-payment.

===Enable Suspension===
Selecting this option will enable automatic suspensions when payments for products or services are overdue. The setting below (Suspend Days) controls the amount of time between your customer becoming overdue and when the system suspends them.

===Suspend Days===
If you enabled Enable Suspension, this configures the amount of time between a customer's product or service becoming overdue and the system suspending them.

===Enable Unsuspension===
When you enable this setting, services that the system suspended due to "Overdue on Payment" will automatically become unsuspended when they pay the unpaid invoice for the item. However, if you suspended products or services manually, and assigned a custom reason for suspension, then an automatic reactivation will not occur. For example, you may have manually suspended an item with a reason of "Broken Terms of Service" or "Awaiting ID Verification".

===Enable Termination===
Enable this option to terminate the client's service (remove it from the server) according to the setting below (Termination Days).

===Termination Days===
If you selected Enable Termination, this determines the number of days between a product or service becoming overdue and the system terminating that product or service.

==Billing Settings==
[[File:Billing Settings.png|thumb|Billing Settings]]
Use these settings to determine how the system generates invoices and sends payment reminders to your customers. Setting the Unpaid and Overdue Reminder settings to <tt>0</tt> will prevent the system from sending the related emails.

===Invoice Generation===
This is the number of days before the system will generate due date invoices. For example, if this setting is <tt>7</tt>, the system will generate an invoice seven days before the due date for products, services, addons, and domains. The number of days should be an integer of <tt>0</tt> or more.

====Per Billing Cycle Settings====
By clicking '''Advanced Settings''', you can specify a different invoice generation setting for each billing cycle. For example, you may want the system to generate invoices for monthly services seven days in advance and generate invoices for annual services 14 days in advance.

====Domain Invoice Generation====
This optional setting allows you to specify how far in advance to generate domain renewal invoices. You can use this if you want to give a longer time between invoice generation and the due date for domain invoices. This is particularly useful when you don't accept payments online and more time might be necessary to avoid domain expiration.

Leave this setting blank if you want the system to generate all invoices at the same time.

===Payment Reminder Emails===
If you enable this, the system will remind your customers by email in advance of an unpaid invoice's due date. It does this using the ''Invoice Unpaid Reminder'' setting (below). This setting does not apply to Overdue Reminders.

===Invoice Unpaid Reminder===
The system sends this email before the due date if the invoice remains unpaid, to remind a customer that the invoice will be due soon.

=== Overdue Reminders===
If a customer hasn't paid an invoice in a certain number of days after the due date, the system will email the customer with a reminder.

===Add Late Fee Days===
If a customer hasn't paid an invoice that is this number of days overdue, your customer will be charged late fees (according to your choices in General Settings).

===Overage Billing Charges===
Use this to determine how to bill clients for overage (if you enabled this). The first setting will calculate the bandwidth overage costs on the last day of each month and create an invoice that is due immediately. This will create a separate invoice.<br />
The second setting will still calculate the overage change on the last day of the month, but it will not create a separate invoice. Instead, the system will add it to the client's next invoice.

===Change Invoice Status===

Select this to use the ''Collections'' invoice status to denote invoices that are bad debts ([[Payment_Reversals|payment reversals]]). You can use this to track invoices that have received payment disputes or chargebacks.

<div class="docs-alert-info">
WHMCS 8.3 and higher includes support for disputes for [[Stripe]] and some [[PayPal]]® transactions at '''Billing > [[Disputes]]'''.
</div>

===Change Due Dates===
Part of the [[Payment_Reversals|Payment Reversals]] feature. This reverts Next Due Date Increments for the products and services in an invoice. The system considers them as due again, and, in cases where the date is in the past, overdue, which will trigger an automated suspension until repayment is made.

==Payment Capture Settings==
[[File:Credit Card Charging Settings.png|thumb|Payment Capture Settings]]
<div class="docs-alert-info">
Prior to WHMCS 8.2, these settings were under '''Credit Card Charging Settings'''.
</div>
Use these settings to determine how to charge your customer's pay method when you use a merchant gateway to handle credit card and other payments.

===Process Days Before Due===
This specifies the number of days before the due date that you wish to capture. For example, setting this to <tt>1</tt> would attempt to charge the card for the first time one day before the invoice due date.

=== Attempt Only Once===
By default, the system will attempt to capture payment for unpaid invoices daily until it succeeds. When you enable this option, WHMCS will only attempt to charge the customer’s card once. If it fails, it will not try again until the client or an admin makes a manual payment attempt.

===Retry Every Week For===
When you enable this, WHMCS will attempt to charge the card every Seven days from the expected capture attempt date for this number of weeks.
For example, if an invoice's '''Next Due Date''' value is on the 14th and you set this setting to <tt>2</tt> and '''Process Days Before Due''' to <tt>1</tt>, the system will attempt the first payment capture on the 13th. Then, it will retry payment on the 20th and 27th if the invoice status is not ''Paid''.

You can also set this setting to <tt>0</tt> to disable the weekly retries, causing the system to attempt to charge the card every day until it succeeds or the invoice status changes to ''Cancelled''

===CC Expiry Notices Date===
This is the day of the month on which the system will send reminder emails to active clients with cards that expire by the end of the month, asking them to update their records. On the 1st of the month, WHMCS will remove any credit cards with an expiration date before that day's date.

We recommend a low value, such as <tt>1</tt>, to give clients as much notice as possible to update their card details. For example:

'''Scenario'''<br/>
Card Expiry Date: March 2020<br/>
CC Expiry Noticed Date: 1

'''Timeline of Events'''<br/>
Reminder email sent: 1st March 2020<br/>
Card removed from WHMCS: 1st April 2020

===Do Not Remove CC on Expiry===
When you enable this option, the client's credit card information will remain on file after its expiration date. When you disable this, the system will remove the credit card details using the setting you specified for CC Expiry Notices Date.

==Currency Auto Update Settings==
[[File:Currency Auto Update Settings.png|thumb|Currency Auto Update Settings]]
Use these settings for the multi-currency system.

===Exchange Rates===
When you enable this setting, WHMCS will connect with the European Central Bank and obtain the latest exchange rates. This will ensure your currency conversion functions are always using an accurate rate. For more information, see the list of [[Currencies#Auto_Updating_Rates |supported currencies]].

===Product Prices===
When you enable this setting, the system will automatically update your prices according to the exchange rates. For example, if you have a product that costs $1 in your default base currency (USD) and the exchange rate is 0.6 for a second currency (GBP), the product’s price would automatically update to £0.6. Tomorrow, if the exchange rate changed to 0.7, a $1 product would change to £0.7.

==Domain Reminder Settings==

[[File:Domain Reminder Settings.png|thumb|Domain Reminder Settings]]

You can configure WHMCS to send Domain Renewal Notices before and after a domain has expired and, in WHMCS 8.2, choose whether to send renewal notices for free domains bundled with a product or service.

For more information on this functionality, see [[Domain Renewal Notices]] and [[Free Domains]].

=== Renewal Notices ===

You can send a maximum of five reminders.

To configure these settings, for each renewal notice:

# Enter the number of days for that notice. If you set any field to <tt>0</tt> it will disable that email.
# Select whether to send the reminder that many days before or after the renewal date.

=== Free Domain Reminders ===

In WHMCS 8.2 and later, choose whether to send renewal reminders for free domains associated with a paid product or service. This setting defaults to disabled for existing installations upgrading to WHMCS 8.2 and to enabled for new installations of WHMCS 8.2 and higher.

For more information, see [[Free Domains]].

==Domain Sync Settings==

[[File:Domain Sync Settings.png|thumb|Domain Sync Settings]]

===Domain Sync Enabled===
Enable this setting for the domain date and status synchronisation function.

<div class="docs-alert-info"><i class="fa fa-question-circle"></i> For more information about the domain sync task, see [[Domain Synchronisation]].</div>

===Sync Next Due Date===
Use this setting to choose whether to sync the Next Due Date to the Expiry Date, and, if you wish, how many days in advance of it.

===Domain Sync Notify Only===
If you enable this, the domain sync script won't make any changes. It will only notify admins of the changes it would have made. This is useful for debugging.

===Domain Expiry Sync Frequency===
A value of <tt>0</tt> will check the domain expiration dates every four hours. Use this setting to set a different frequency. The lowest frequency setting, <tt>1</tt>, will check every hour.

===Pending Transfer Sync Frequency===
A value of <tt>0</tt> will check the domains in Pending Transfer status every four hours. Use this setting to set a different frequency. The lowest frequency setting, <tt>1</tt>, will check every hour.

==Support Ticket Settings==
[[File:Support Ticket Settings.png|thumb|Support Ticket Settings]]
===Close Inactive Tickets===
After this amount of time has passed, the system will close any tickets that meet both of the following criteria:

* The ticket's status is either answered or customer reply.
* There have been no new replies from staff or the customer.

The system will also send an email to the customer.

Tickets in on hold and in progress status are exempt from auto-closure. Closure takes place when the daily cron job runs.

<div class="docs-alert-info">You must configure Ticket Statuses to "Auto-Close" for this setting to take effect. You can learn more about Ticket Statuses and the Auto-Close functionality in our [https://docs.whmcs.com/Support_Ticket_Statuses#Status_Options Status Options documentation].</div>

===Prune Ticket Attachments===
When this setting is enabled, ticket attachments will be automatically deleted after the selected amount of time of inactivity following the closure of a ticket. This can be set between 1 and 24 months.

For more information on this functionality, see the [[Ticket Attachment Pruning]] documentation.

==Data Retention Settings==
[[File:Data Retention Settings.png|thumb|Data Retention Settings]]

===Automatically Delete Inactive Clients===

<div class="docs-alert-info">
<span class="title">Automatically Delete Inactive Clients</span><br />
* We added this setting in WHMCS 7.5.
* In WHMCS 8.3 and earlier, this was the '''After no invoice or transaction activity has occurred for the following number of months''' setting.
</div>

This setting allows you to configure client records to be automatically deleted after a given number of months with no invoice or transaction history. The length of time you must retain data is often governed by the laws and regulations of your local jurisdiction. Most jurisdictions agree that you should only keep personal data for as long as is necessary.

To enable this setting, select '''After no invoice payment has occurred for the inactive or closed client in the following number of months''' and specify a number of months that is greater than <tt>0</tt>.

This setting is disabled by default.

<div class="docs-alert-danger">
<span class="title">Paid Invoices and Transactions</span><br />
The presence of paid invoices or transactions within the specified period determines whether WHMCS retains client records. If you enable this feature, WHMCS will immediately delete clients who are in the ''Inactive'' or ''Closed'' statuses and have no invoice or transaction history.
</div>

This setting causes the system to perform the '''Data Retention Pruning''' task each day. This will delete client records that meet the following criteria:

* A status of [[Automation_Settings#Client_Status_Update|'''Inactive''' or '''Closed''']].
* No paid invoices within the specified number of months.
* No entered or applied transactions within the specified number of months.
* If the client is an affiliate, a commission balance of <tt>0</tt> or no referrals within the specified retention period.

<div class="docs-alert-info">The system can automatically change the client status. Use the '''[[Automation_Settings#Client_Status_Update|Client Status Update]]''' setting to control this.</div>

=== Delete associated users if the user(s) are not associated with any other client account===

Optionally, you can set this to '''YES''' to cause the '''Data Retention Pruning''' task to also delete users who are only associated with this client.

==Miscellaneous==
[[File:Miscellaneous.png|thumb|Miscellaneous]]
===Cancellation Requests===
When you enable the [[Other_Tab#Show_Cancellation_Link|Show Cancellation Link]] option, enabling this setting will automatically terminate the client’s package on the termination date.

For more information, see [[Cancellation Requests]].

===Update Usage Statistics===
Enabling this option will display disk and bandwidth usage statistics from the hosting control panel (if it is supported) inside the WHMCS admin and client areas. It will update them on a daily basis.

===Client Status Update===
The following applies to the client status dropdown found in the client account Profile tab. WHMCS automatically sets clients older than 2 days, with no active products or services to Inactive status. This helps you to distinguish and filter clients effectively. However, you can stop WHMCS from doing this by changing this setting. More information on this feature is available in [[Clients:Profile_Tab#Changing_a_Clients_Status|Client Management]].

'''Disabled''' — The system won't change the status of a client automatically.

'''Change client status based on active/inactive products''' — If a client was created more than 2 days ago, has no active or suspended services, domains, addons, or billable items, the system will automatically set their account to Inactive status the next time that the cron job runs.

'''Change client status based on active/inactive products and not logged in for longer than 3 months''' — In addition to the above option, the system will only set a client's account to inactive when their last login date was over 3 months ago.

===Module Log Pruning===
Enabling this option allows you to choose the number of days of [[System_Logs#Module_Log|module log]] entries to retain. The system prunes the module log daily during the execution of the cron.

Products and Services

2024-02-19T11:57:35Z

PeterM:

Configuring products and services in WHMCS allows you to determine the specifics for each of your offerings.

You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Products/Services''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.

== Product Groups ==

Product groups organize products and product bundles on the order form. Each group has a separate page, and you can group products in categories or across several pages. For example, you may wish to list your shared hosting plans separately from reseller plans.

Product groups list similar or related products together, allowing them to display side-by-side for comparison in some order form templates. You must create at least one product group before you can create a product.

* Clients can switch between groups on the order form or you can link to them directly (see [[#Links|Links]] below).
* To customize how the system sorts groups when displaying them, see [[#Sorting|Sorting]].

To create a product group:

# Click '''Create a New Group'''.
# Specify the following product group information. Some order form templates may not use all of this information:
## '''Product Group Name''' — The name that the system displays for the group to both admin users and customers. The name that you enter here will display on the order form.
## '''URL''' — In WHMCS 8.0 and later, a friendly form of the product group's URL. This value must contain at least one letter. Use this to customize product group links. For more information, see [[Friendly URLs]].
## '''Product Group Headline''' — A headline. Older order form templates may use the product group name as the headline instead.
## '''Product Group Tagline''' — A tagline.
## '''Order Form Template''' — Allows you to define the order form template for the product selection and product configuration pages if you do not want to use the default. <div class="docs-alert-warning"><span class="title">Note</span><br />If the <tt>?carttpl=xxx</tt> URL parameter specifies an order form template to use, then that value will take precendence over the product group setting.</div>
##* Normally, all product groups use the system default order form template that you specify in the '''[[Ordering Tab|Ordering]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
##* The system will use the template you select to display products when the product group is selected from the list of available product categories in the shopping cart, and for the product configuration steps of any products or bundles in the group.
## '''Available Payment Gateways''' — Allows you to customize which active payment gateways you can use with orders and invoices containing products from this group. <div class="docs-alert-warning"><span class="title">Warning</span><br />If an order or invoice contains multiple products from multiple different product groups, only payment gateways that the two product groups share in common will display. For this reason, it's important that product groups share '''at least''' one payment gateway in common. If a client orders items from two groups that don't have a gateway in common, it would result in no payment gateways being available for payment.</div>
##* By default, all active payment gateways are available to all orders and invoices that you create within WHMCS.
##* Any gateways with a check beside their name will display as possible choices for orders containing products within a given group. To prevent a gateway's use with products from a product group, uncheck the checkbox next to the name.
## '''Hidden''' — Hides the product group from display in the client side '''Shopping Cart''' product group list. The group remains accessible using the group ID.
# Click '''Save Changes'''.

After creating the group, you can edit it by clicking the edit icon for the group in the '''Products/Services''' list.

=== Group Features ===

<div class="docs-alert-warning">
You can only edit '''Group Features''' information after you save the product group for the first time.
</div>

Adding product group features allows some newer order form templates to display features that relate to all the products within the group.

* To add a feature, enter the display text for it and press enter or click '''Add New'''. The system will add the feature to the bottom of the list.
* To edit a feature, you will need to delete and recreate it.
* To reorder features, click and drag the crosshair icon to the left of the feature label.
* To delete a feature, click the X icon to the right of the features.

== Products ==

To create a new product:

# Click '''Create a New Product'''.
# Select one of the following product types:
#* '''Shared Hosting''' — Use this type for products that will provision a shared hosting account.
#* '''Reseller Hosting''' — Use this type for products that will create a reseller hosting account (for example, a cPanel reseller account).
#* '''Server/VPS''' — Use this type when selling a server (for example, a VPS or dedicated server). The client must select a hostname, <tt>root</tt> password, and nameserver prefixes when they order this product.
#* '''Other''' — Use this type for anything that isn't a hosting product (for example, software licensing). Product types do not affect billing in any way. However, depending on the assigned server module, they may affect behavior and the Client Area service details page (including login options).
# Select a group from the '''Product Group''' menu.
# Enter a product name in the '''Product Name''' text box.
# In WHMCS 8.3 and later, enter the desired product URL in the '''URL''' text box or use the default generated product URL. For more information, see [[Friendly URLs]].
# Select a module from the '''Module''' menu. For example, for hosting plans on a Plesk server, select ''Plesk''.
# Toggle '''Create as Hidden''' to set whether the system hides or displays the product to clients on the Client Area order form.
# Click '''Continue'''.
# Configure the tabs on the page that appears. For more on these tabs, see the sections below.
# Click '''Save Changes'''.

After creating the product, you can edit it by clicking the edit icon for the product in the '''Products/Services''' list.

To customize how the system sorts products when displaying them, see [[#Sorting|Sorting]].

=== Details ===

The '''Details''' tab contains general information about a product, including its name and product group:

* '''Product Type''' — Select a product type. For more information, see the [[#Products|Products]] section above.
* '''Product Group''' — Select a product group.
* '''Product Name''' — Enter a product name.
* '''Product Tagline''' — In WHMCS 8.5 and later, enter a product tagline. This tagline displays when this product displays as a [[Cross-selling_and_Product_Recommendations_In_WHMCS|recommendation]].
* '''URL''' — In WHMCS 8.3 and later, enter the desired product URL in the '''URL''' text box or use the default generated product URL. For more information, see [[Friendly URLs]].
* '''Product Short Description''' — In WHMCS 8.5 and later, enter brief information that relates to this product on the order form. This description displays when this product displays as a [[Cross-selling_and_Product_Recommendations_In_WHMCS|recommendation]].
* '''Product Description''' — Enter detailed information that relates to this product on the order form.
** The system maintains line breaks when you format a description.
** When using HTML, we recommend avoiding new lines unless you want them to appear in the end result.
** When the <tt>key: value</tt> format is used in the description, WHMCS will apply the [[Standard_Order_Form_Templates#Feature_Highlights|Feature Highlights]] styling.
* '''Product Color''' — In WHMCS 8.5 and later, click to use a color picker to select the product's main color when it displays as a [[Cross-selling_and_Product_Recommendations_In_WHMCS|product recommendation]].
** Click to select a color, use the color slider, or enter '''RGB''' values to choose a color.
** The system will generate a secondary color when it displays the recommendation in the Client Area.
* '''Welcome Email''' — Select the email template to send when activating the product. You can create custom email templates to use on different products. For more information, see [[Email Templates]].
* '''Require Domain''' — Check to display domain registration option when ordering the product. Always enable this for hosting and disable it for other products that don't require a domain name.
* '''Stock Control''' — Check to enable a stock control limit and then enter the available quantity of the item (for example, servers) or a limited special-offer product. WHMCS will stop orders when the available quantity is <tt>0</tt>.
* '''Apply Tax''' — Check to apply tax rules to this product. For more information, see [[Tax Configuration]].
* '''Featured''' — Check to display a product more prominently. This option is only available on some supported order forms.
* '''Hidden''' — Check to show the product on the order form. Customers will still be able to order this using the direct order links.
* '''Retired''' — Check to hide the product from [[Admin Area]] menus, like the product menu in the client's profile.

=== Pricing ===

The '''Pricing''' tab lets you specify the prices and active duration of the product.

[[File:Cpanel standalone2.png|thumb|Price Grid]]

* '''Payment Types''' — Select '''Free''', '''One Time''', or '''Recurring'''. If you select '''One Time''' or '''Recurring''', the pricing grid will appear. Enable the desired billing cycles by checking '''Enable'''.
** For '''One Time''' products, enable '''One Time/Monthly''' and enter your prices into that column.
** For '''Recurring''' products, check '''Enable''' for the billing cycles that you want to offer with the product.
** For '''Setup Fee''' in each column, enter any setup fees for a given billing cycle. For example, you may charge setup fees on monthly cycles and offer free setup for yearly cycles.
<div class="docs-alert-info">
When you set '''Payment Type''' to ''Free'':
* The product can be perpetual or a one-time service.
* There will be no '''Expiry Date''' or '''Next Due Date''' values.
* The system will not generate invoices.
* No renewals will occur.
* Clients cannot submit a cancellation request via the Client Area.
</div>
* '''Allow Multiple Quantities''' — Select whether clients can order multiple instances of this product on the checkout page. The product cannot require additional configuration (like product custom fields or configurable options).
** ''No'' — Disables the option to specify a quantity for this product.
** ''Yes - Multiple Services'' — Each unit represents its own individual service instance. For example, specifying a quantity of <tt>10</tt> will create 10 service records upon ordering, each with its own price based on the product price. The service Recurring Amount is equal to the product price.
** ''Yes - Scaling Service'' — Each service instance allows a quantity to be defined. For example, specifying a quantity of <tt>10</tt> will create one service, with the product price multiplied by 10. This is stored in the service's '''Recurring Amount''' field.
* '''Recurring Cycles Limit''' — For '''Recurring''' payment types, the default value (<tt>0</tt>) will invoice indefinitely until cancelled. However, by entering a value in this field, you can limit the number of times clients will be invoiced for this product. For example, entering <tt>5</tt> on a monthly product prevents the system from generating an invoice in the 6th month after ordering.
* '''Auto Terminate/Fixed Term''' — You can set up products that automatically terminate after a set number of days from the service's registration date.
** To enable this, enter the number of days to wait before terminating. Then, choose an email template to send to the client when termination occurs (for example, confirmation of completed payment for installment payments).
** Set this to <tt>0</tt> to disable this feature.
** Entering a number in this field terminates the product when the cron job runs that many days after the product registration date.
** Use this to offer free trial products for a certain period of time or time-limited products that should only recur for a certain number of cycles before stopping.
** For more information, see [[Common Promotions]].
* '''Termination Email''' — If you entered an '''Auto Terminate/Fixed Term''' value, select an email to send to the client at product termination.<div class="docs-alert-info">'''Termination Email''' only includes custom product-type email templates. For more information, see [[Email Templates]].</div>
*'''Prorata Billing''' — This allows you to bill products on a specific day of the month and charge a prorata amount at the initial time of order. If you check this, the system will charge all clients on one specific day each month. Otherwise, the product will use the default anniversary billing system (for example, Jun 15–Jul 15). Changes to this setting apply to new orders only.<div class="docs-alert-info">Prorata billing is not compatible with free domains or having domain renewal invoices that the system generates further in advance than other products.</div>
* '''Prorata Date''' — The specific billing date for all sales of the product. If you set this to <tt>1</tt>, the system will charge all clients on the 1st of each month.
* '''Charge Next Month''' — After this day of the month, the system will also charge a client for the next month in their initial payment when signing up on a monthly billing cycle.
** If you don't enable this, you set the prorata date to 1, and a client signs up on the 30th of the month, they would only pay a small amount.
** If you enable this, they would pay the prorated amount plus the next month in advance.
** To prorate a product but not enable this feature, set '''Prorata Date''' to a normal value and set '''Charge Next Month''' to <tt>32</tt>.
* '''On-Demand Renewals''' — Configure product-specific settings for on-demand renewals.<div class="docs-alert-info">We moved these settings to the '''Pricing''' tab in WHMCS 8.9. For more information, see [[On-Demand Renewals]].</div>
** To use the global configuration in the '''[[Ordering_Tab|Ordering]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''', select '''Use System Default'''.
** To override the global configuration and '''always''' offer on-demand renewals for the product, select '''Use Product-Specific Configuration''' and check '''Check to allow clients to place renewal orders early'''.
*** Optionally, enter the maximum length of the on-demand renewal period for each billing cycle.
*** Enter <tt>0</tt> to disable on-demand renewals for that billing cycle.
** To override the global configuration and '''never''' offer on-demand renewals for the product, select '''Use Product-Specific Configuration''' but do '''not''' check '''Check to allow clients to place renewal orders early.'''.

=== Module Settings ===

This tab specifies which server type the product will use and how WHMCS will behave when someone orders this product.

* From '''Module Name''', select the type of server you're using. If a product has no specific module to link to, set it to ''[[Auto_Release|Autorelease]]'' to simulate activation and send a welcome email.
* The options you see depend on the module you chose. For more information, see the [[Server_Modules|Provisioning Modules]] section.
* At the bottom of the page, the automation settings determine when the system activates the product.
** '''Automatically setup the product as soon as an order is placed''' — Set the product up instantly. Generally, use this for free products.
** '''Automatically setup the product as soon as the first payment is received''' — Set the product up when the customer pays for the order.
** '''Automatically setup the product when you manually accept a pending order''' — Set the product up after an admin has manually reviewed and accepted the order.
** '''Do not automatically setup this product''' — Never set the product up automatically. Admins can still initiate setup manually from the product details page under a client's profile.

====Metric Billing====

[[File:Usage-billing-module-settings-metric-config-83.png|thumb|]]

<div class="docs-alert-info">
'''[[Usage Billing|Metric Billing]]''' displays when you select a module that supports this feature in WHMCS 7.9 and later.
</div>

If a metric is enabled, it will appear within the client's product details view of the client area. An admin will always see all metrics, enabled or disabled, within the admin area when viewing a service belonging to a product which reports metrics.

To enable a metric for billing or display purposes:

# Set that toggle to '''On'''.
# Click '''Configure Pricing''' for that metric. The module predefines the following attributes for each metric:
#* '''Metric Type''' — Defines how the metric is measured. This can be '''Snapshot''', '''Daily''', or '''Monthly'''.
#* '''Metric Unit''' — Defines the unit of measurement (for example, the number of domains or accounts).
# Select the type of pricing scheme. This will define how the system calculates pricing for the metric.
#* You can select one of the following pricing schemes:
#** '''Per Unit''' — Charge the same amount for each unit.
#** '''Total Volume''' — Charge a per-unit price based on the total volume consumed.
#** '''Graduated''' — Charge a per-unit price based on the consumption range. The total charge is the sum of the range calculations.
#* For '''Total Volume''' and '''Graduated''' pricing schemes, you '''must''' enter pricing in the text boxes.
#* For more information and examples of each pricing scheme, see [[Usage Billing]].
# In '''Quantity Included''', enter the number of units to include in the product's base price. Charging will not commence until the usage exceeds the quantity defined here.
# Click '''Save'''.

===Custom Fields===

From this tab you can create custom fields for this product. This allows you to collect additional order form information that you need to supply the product.

To add a custom field to your clients' profiles:

# Locate the desired custom field to edit or create a new custom field under '''Add New Custom Field'''.
# Enter the requested field information and choose a field type.
# Check the appropriate checkboxes to show or hide the field or require a response.
# Click '''Save Changes'''.

<div class="docs-alert-info">
You can configure custom fields for your clients' profiles at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Custom Fields]]''' or, prior to WHMCS 8.0, '''Setup > Custom Client Fields'''.

For more information about custom field configuration, see [[Custom Fields]].
</div>

===Configurable Options===

Use this tab to select the [[Configurable Options|configurable options]] to associate with the product. You can display them on the order form or in the Client Area. Configurable options alter the price of the product.

===Upgrades===

Use this tab to specify whether the client can upgrade or downgrade from this product to another. WHMCS can fully automate upgrades and downgrades for many of the modules.

* Select the products that the product can be upgraded or downgraded to.
* Use <tt>Ctrl+Click</tt> to select multiple products.
* Check '''[[Configurable Options]]''' to enable upgrading configurable options, if there are any on the product.
* Select an '''Upgrade Email''' template to use when a client upgrades to this product. You will first need to create a new product email template under '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Email Templates]]''' or, prior to WHMCS 8.0, '''Setup > Email Templates'''.

For more information, see [[Automated_Upgrades_and_Downgrades|Automated Upgrades and Downgrades]].

===Free Domain===

Use this tab to configure the offer of a free domain with a product. WHMCS lets you offer free domains with your packages when customers purchase them with certain payment terms. For example, you might want to offer a free domain when someone purchases a package annually.

*For '''Free Domain''', choose whether and how to offer a free domain.
*Select one or more '''Free Domain Payment Terms''' to set the billing cycles that are required for a product to receive a free domain.
*Select one or more '''Free Domain TLDs''' to set which TLDs can be used for a free domain.

For more information, see [[Domains_Configuration#Offering_Free_Domain_Registration_with_Selected_Packages|Offering Free Domain Registration]] and [[Common Promotions]].

===Cross-sells===

<div class="docs-alert-info">
We added cross-selling and product recommendations in WHMCS 8.5. For more information, see [[Cross-selling and Product Recommendations In WHMCS]].
</div>

Use this tab to choose the recommended products that display in the Client Area shopping cart to clients who are purchasing this product.

To add products to the list:

# Use the '''Start typing to search for products.''' menu or enter search terms to find the desired products.
# Select the desired product by clicking on it.
#* When you select a product, it will appear in the '''Product Cross-sells''' list.
#* Click and drag the product to the desired position to reorder the list.
# Click '''Save Changes'''.

To remove a product from the list, click the trash icon and then click '''Save Changes'''.

===Other===

Use this tab to set miscellaneous settings such as product affiliate rates, product downloads, and overage billing.

* '''Custom Affiliate Payout''' — Select whether to provide a percentage of the price, provide a fixed amount per sale, or disable commissions. <div class="docs-alert-info">Selecting '''No Commission''' disables commissions for the product. This setting overrides the default commission. However, if you configure either the affiliate or product commission to one-time, that selection will override this setting.</div>
* '''Affiliate Pay Amount''' — The percentage or amount paid for a purchase of this product, depending on your choice for the setting above.
* '''One Time Payout''' — Whether to prevent subsequent commission payments when the product renews.
** If you do not check this, the affiliate will receive a commission every time that the product renews.
** If you did '''not''' select '''Fixed Amount''', set '''Affiliate Pay Amount''' to <tt>0.00</tt>.
* '''Subdomain Options''' — Enter a domain in the format <tt>.example.com</tt> to offer a free subdomain for the domain at signup. You can offer more than one by entering a comma separated list (for example, <tt>.example.com,.example.net</tt>).
* '''Associated Downloads''' — The files to automatically release to the customer when the product is activated.
** Click '''Add Category''' to create a new category of downloads.
** Click '''Quick Upload''' to upload a new file.
** For more information, see [[Product Downloads Distribution]].<div class="docs-alert-info">You can delete categories and files at '''Support > [[Downloads]]'''.</div>
* '''Overages Billing''' — Enable billing for the product based on disk and bandwidth usage for the month. For more information, see [[Disk Space and Bandwidth Overage Billing]].
* '''Soft Limits''' — Enter the soft limits for '''Disk Usage''' and '''Bandwidth'''.
* '''Overage Costs''' — Enter the overage costs for '''Disk Usage''' and '''Bandwidth'''.
* '''On-Demand Renewals''' — Configure product-specific settings for on-demand renewals.<div class="docs-alert-info">We added this feature in WHMCS 8.8 and moved these settings to the '''[[#pricing|Pricing]]''' tab in WHMCS 8.9. For more information, see [[On-Demand Renewals]].</div>
** To use the global configuration in the '''[[Ordering_Tab|Ordering]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''', select '''Use System Default'''.
** To override the global configuration and ''always'' offer on-demand renewals for the product, select '''Use Product-Specific Configuration''' and check '''Check to allow clients to place renewal orders early.'''. Optionally, enter the [[On-Demand_Renewals#Renewal_Period_Lengths|maximum length of the on-demand renewal period]] for each billing cycle. Enter <tt>0</tt> to disable on-demand renewals for that billing cycle.
** To override the global configuration and ''never'' offer on-demand renewals for the product, select '''Use Product-Specific Configuration''' but do '''not''' check '''Check to allow clients to place renewal orders early.'''.

===Links===

[[File:link-tab-urls-83.png|thumb|]]

Use this tab to view the URLs that direct visitors to a product.

* When a visitor accesses the '''Direct Shopping Cart Link''', '''Direct Shopping Cart Link Specifying Template''', or '''Direct Shopping Cart Link Including Domain''' URLs, the product will automatically be added to the shopping cart and the visitor will proceed automatically to the configuration step.
* When a visitor accesses the '''Product Group Cart Link''' URL, the visitor will go directly to the product group page.
* When a visitor accesses any of the URLs in the '''Product URLs''', they will be redirected to the '''Direct Shopping Cart Link''' URL.
** Each time that a new visitor accesses the link, the '''Visits''' count will increase.
** To delete a product URL, click the corresponding red delete button.
*** You '''cannot''' delete the active URL.
*** When you delete a product URL, the URL will become nonfunctional.

For more information, see [[Linking to WHMCS]] and [[Friendly URLs]].

==Sorting==

You can sort groups and products using the crosshair icon in the appropriate row. This is on the left for groups and on the right for products.

[[File:Drag_and_drop_sorting.png|center|850x250px]]

After moving, a success message will appear on the top right of the page to confirm that the system saved the sort order. It is not possible to move products between groups using the drag-and-drop method.

==Feature Highlights==

Feature highlights allow you to define features and their values for products in a way that WHMCS can interpret for comparison-based display.

The system supports '''Feature Highlights''' for most order form templates. For more information, see [[Standard_Order_Form_Templates#Templates|Standard Order Form Templates]].

Custom Fields

2023-12-19T15:11:27Z

PeterM: /* Show on Order Form */

Custom fields allow you to collect additional information from your clients. WHMCS allows you to set up an unlimited number of customer fields that apply to clients, individual products and services, and support departments. You can set them as either admin-only for private use or public.

For example, you might create custom questions like how a client found your site, whether they want to join the mailing list, or their VAT/Tax Number.

== Client Custom Fields ==

Custom fields for clients display in the client's profile for admins, clients, or both and can optionally display on the order form. Set these to '''Show on Order Form''' if you want the client to enter them. You can also leave them as only visible in the admin area, for private entries. The client can view and edit the field values from the client area unless you set them to admin only.

To add a custom field to your clients' profiles:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Custom Fields''' or, prior to WHMCS 8.0, '''Setup > Custom Client Fields'''.
# Locate the desired custom field to edit or create a new custom field under '''Add New Custom Field'''.
# Enter the requested field information and choose a field type.
# Check the appropriate checkboxes to show or hide the field or require a response.
# Click '''Save Changes'''.

<div class="docs-alert-success">
<span class="title">Searching</span><br />
* You can search for the values from custom client fields at '''Clients > View/Search Clients''' in the '''Search/Filter''' tab.
* To search a '''Checkbox''' custom field, enter "on" in the '''Custom Field Value''' field. This will display results that include the checked option.
</div>

== Product Custom Fields ==

Custom fields for products display as part of the configuration process when clients purchase a product, or you can choose to only display them in the Admin Area for purchased products. This allows you to collect further information that's specific to an individual product.

Some modules require specific fields, which you can find in the documentation for that module.

You can configure custom product fields in the '''Custom Fields''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services'''.

<div class="docs-alert-success">
<span class="title">Searching</span><br />
* You can search for the values from custom product fields at '''Clients > Products/Services''' in the '''Search/Filter''' tab for the desired product group.
* To search a '''Checkbox''' custom field, enter "on" in the '''Custom Field Value''' field. This will display results that include the checked option.
</div>

== Support Department Custom Fields ==

Custom fields for support departments display during ticket submission, or you can optionally choose to only display them in the Admin Area. They allow you to ask users for additional information when opening tickets. The system can use this for things like current usernames and passwords.

You can configure custom support department fields in the '''Custom Fields''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Support Departments]]''' or, prior to WHMCS 8.0, '''Setup > Support > Support Departments'''.

== Field Types ==

When you create a custom field, you can choose from the following field types:

* '''Text Box''' — For a text entry.
* '''Link/URL''' — A URL. The prefix http:// will automatically be prefixed to any value entered.
* '''Password''' — A value to be encrypted, will appear as a password field type in the client area.
* '''Drop Down''' — A drop-down combo box for a selection of preset options.
* '''Checkbox''' — For a yes-or-no answer.
* '''Text Area''' — For a long text entry of multiple lines.

== Validation ==

The regular expression validation rules allow you to define what value the field can accept. The system won't allow the user to proceed until it passes the validation rule. For example:

A domain name in the format "google.com":
/^([a-zA-Z0-9_-])+(\.[a-zA-Z0-9_-]+)*\.([a-zA-Z]{2,6})$/

A username between 4 and 28 characters in length, allowing only alphanumeric characters and underscores:
/^[a-z\d_]{4,28}$/i

A telephone number in the following format: (###) ###-####
/^($?[0-9]{3,3}$?|[0-9]{3,3}[-. ]?)[ ][0-9]{3,3}[-. ]?[0-9]{4,4}$/

A date in the format DD/MM/YYYY:
/^\d{1,2}\/\d{1,2}\/\d{4}$/

Numbers only (0-9, any length):
/^[0-9]+$/

See http://www.rexegg.com/regex-quickstart.html for a detailed guide.

<div class="docs-alert-warning">
You must properly escape any forward slashes in your regular expression using back slashes: \/
</div>

== Other Settings ==

Depending on the type of custom field you are creating, you can enable the following options:

=== Admin Only ===

Check '''Admin Only''' if you want to hide this in the Client Area.

=== Required Field ===

Check '''Required Field''' if you want to require a response.

=== Show on Order Form ===

Check '''Show on Order Form''' if you want to display this field on the order form in the Client Area when a client is registering.

=== Show on Invoice ===

Check '''Show on Invoice''' if you want this field to display on the client's invoices.

You might want to display custom fields on invoices if, for example, you have a client custom field for a Tax ID or VAT Number.

* Client custom fields will display under the name and address information on the invoice.
* Product custom fields display as part of the line item descriptions for those products.

If you enable '''Store Client Data Snapshot''' in the '''[[Invoice Tab|Invoices]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. Then, create or edit a custom field after invoice creation, the invoice won't reflect those changed values and new fields. However, future invoices will show them.

==Displaying Custom Fields in Emails==

You can add custom fields to email templates using merge fields. For more information, see [[Email_Templates#Merge_Fields|Email Templates]].

==Displaying Custom Fields on Pages==

To display custom fields on service-related pages, the merge fields take the following format, where <tt>fieldname</tt> is the name of the custom field, lowercase with no spaces:

<div class="source-cli">
{$client_custom_field_fieldnamehere}
</div>

For example, for IP address, the merge field would be:

<div class="source-cli">
{$service_custom_field_ipaddress}
</div>

For fields with Friendly Names, use the friendly name, rather than the machine name, to reference the field. For example, if the field name is:

<source lang="php">CustomerType</source>

Reference it as:

<source lang="php">
{$client_custom_field_customertype}
</source>

However, if the field name is using a friendly name, like this:

<source lang="php">
CustomerType|Type of Customer
</source>

Reference it as:

<source lang="php">
{$client_custom_field_typeofcustomer}
</source>

===Multi-line Text Areas===

For text area custom fields, you can enter data on multiple lines. By default, the system displays it in merge fields on a single line. To see the custom field data as it was entered in the field, use the following merge field:

<source lang="php">
{$client_custom_field_fieldnamehere|nl2br}
</source>
or
<source lang="php">
{$service_custom_field_ipallocation|nl2br}
</source>

==Friendly Display Names==

Sometimes, a module may require that you format a custom field value in a certain way, which may be hard for visitors to understand. WHMCS can display a friendly name to visitors on the order form, emails, and invoices, and still send the required machine code to the module.
[[File:Custom_field_friendly.png|thumb|Custom Field Friendly Names]]
To achieve this, use the format "required value|display value". For example:

*Disk Space|Your Web Quota
*10000MB|10 Gigabytes
*rbx01ssd|French Server - Solid State Drive

GoCardless

2023-11-20T10:53:16Z

PeterM:

== About this Module ==

<div class="docs-alert-success">
We added this payment gateway in WHMCS 7.7.
</div>

[https://gocardless.com GoCardless] is a payment gateway which allows for direct debit payments to be automated electronically.

<div class="docs-alert-info">
<span class="title">Important</span><br />
Due to GoCardless API restrictions, you must have a GoCardless Pro or GoCardless Enterprise account to use this module.
</div>
{{gateways
| onetime = yes
| recurring = yes
| reversals = yes
}}
== Adding the GoCardless Payment Gateway ==

To set up the GoCardless payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''GoCardless'''. A GoCardless login page will appear.
# Either sign up for a new account or log in to your existing account. The system will automatically configure GoCardless for you.
# Optionally, enter a custom name for the gateway for each of your supported currencies.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
#In WHMCS 8.0 and later, enabling '''Charge Date Preference''' will allow the automation system to omit passing a <tt>charge_date</tt> value to GoCardless when the automation system triggers a payment attempt. This results in GoCardless starting the transaction as soon as possible.
# Click '''Save Changes'''.

===Charge Date Preference===

 '''Charge Date Preference''' will determine if WHMCS passes a transaction charge date to GoCardless advising when to initiate the payment.

* Disabling the option will pass through either the '''Next Due Date''' from the service or the <tt>next_possible_charge_date</tt> that GoCardless sets using the <tt>charge_date</tt> function depending on which date is later.

* If you enable the option, the system will not pass a <tt>charge_date</tt> value to GoCardless and this will result in GoCardless beginning the payment process as soon as possible.  In both scenarios, the payment attempt call to GoCardless will not occur until an invoice meets the invoice and payment capture attempt criteria that you set at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]'''.

To process the payment prior to the '''Next Due Date''' date and according to the '''Process Days Before Due''' date at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''', enable this setting. If you do not, the system may attempt the payment on or after the '''Next Due Date''' date.

=== Supported Currencies ===

GoCardless only support the following currencies:

* AUD
* CAD
* DKK
* EUR
* GBP
* NZD
* SEK
* USD <div class="docs-alert-info">We added support for USD in WHMCS 7.9.</div>

Clients who do not use one of these currencies cannot make payments using GoCardless.

=== Test Mode ===

You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful to test your configuration.

==Payment Workflow==

When the first payment is made, a mandate is set up with the client's bank. This typically takes a few days, so the invoice will change from '''Unpaid''' to '''Payment Pending''' status. At this point, you can view the mandate details and expected payment completion date by viewing the invoice. As soon as the mandate is set up and the first payment has cleared, the invoice's status will change to '''Paid''' and the service will be provisioned by WHMCS automatically.

When the renewal invoice is generated for a recurring service, a capture attempt will be made against the mandate in accordance with '''Process Days Before Due''' in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''. As it can take a few days for the payment to complete, we recommend a setting of '''3'''. This way, 3 days before the invoice '''Due Date''', the payment process will be initiated by the cron and the invoice status updated from '''Unpaid''' to '''Payment Pending'''. Payment should then complete on the invoice '''Due Date''' and the invoice will be marked '''Paid''' once the payment has cleared.

Once a mandate has been created, WHMCS can use it for processing renewal payments for any other services associated with the client as long as they are set to the GoCardless gateway as well.

When making a manual payment, customers are able to select to use a previously stored bank account or enter a new one.

Customers never leave your WHMCS installation during checkout or adding/removing a new bank account. Personal bank information is submitted directly to GoCardless and is never stored in your local WHMCS installation.

==Reversed Payments==

The Direct Debit Guarantee scheme allows the payee to file a claim for any payment taken in error. WHMCS will monitor for ''charged_back'' events from GoCardless and will automatically process these as appropriate.

To learn more, visit [[Payment Reversals]]

==Refunding Payments==

While refunds with GoCardless are not directly supported from within WHMCS, they can still be processed directly with GoCardless on a case-by-case basis through their review and approval process.

Please refer to the [https://support.gocardless.com/hc/en-ca/articles/210536269-Refunding-payments refunding payments] section of the GoCardless documentation.

== Mandates ==

<div class="docs-alert-success">
We added these features in WHMCS 7.8.
</div>

=== Reinstating Mandates ===

<div class="docs-alert-warning">
Reinstating mandates requires specific permission from GoCardless.
</div>

When a mandate has been accidentally cancelled, WHMCS can initiate steps to reinstate the mandate without having the client set it up again.

To do this:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Click the '''Manage Existing Gateways''' tab.
# Click '''Manage Cancelled Mandates'''.
# Follow the instructions in the modal that appears to reinstate a cancelled mandate.

=== Importing Existing Mandates ===

<div class="docs-alert-info">
You must disable any automatically-charged mandates that you import in order to prevent possible duplicate charges.
</div>

You can import mandates that you set up outside of WHMCS and associate them with a client.

To do this:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Click the '''Manage Existing Gateways''' tab.
# Click '''Import Existing Mandates'''.
# Follow the instructions in the modal that appears to import a active mandate to a specific client.

=== Removing Mandates ===

You can remove mandates by deleting the client's GoCardless [[Pay_Methods|pay method]].

To do this:

# Click on the pay method in the '''[[Clients:Summary_Tab|Summary]]''' tab of the client profile.
# Click '''Delete''' to [[Clients:Summary_Tab#Removing_Card_Details|remove the pay method]] and any associated mandates.

== Reconfiguring Callbacks ==

After moving WHMCS, you must perform the following steps:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Click '''Configure GoCardless Account Connection'''.
# Log in again using the same details.

This ensures that GoCardless stores and uses the new system URL and gateway callback file URL.

== Troubleshooting ==

===Access token not active===

You can only connect each GoCardless account to a single WHMCS at a time. If you connected the GoCardless Account to multiple WHMCS installations, only the last installation that you connected will function correctly. Previously-connected WHMCS installations will show an <tt>Access token not active</tt> error at '''Billing > [[Gateway Log]]'''.

To resolve this error, you will need to reconnect WHMCS to GoCardless by [[#Reconfiguring_Callbacks|reconfiguring callbacks]].

===Remote Storage "create" action did NOT provide token===
This error indicates the GoCardless account does not have access to the required API endpoint. Due to GoCardless API restrictions, you must have a GoCardless Pro or GoCardless Enterprise account to use this module. For more information, see the [https://developer.gocardless.com/api-reference/#mandates-create-a-mandate GoCardless API documentation].

{{modules}}

Configuring Sign-In using Google

2023-10-24T14:00:44Z

PeterM:

Enabling the Google [[Sign-In Integrations]] enables visitors and customers to register, sign in, and connect their Google accounts with your WHMCS installation for faster signup and automatic sign-in.

[[File:Signinintegrationslogin3.png|600px]]

== Configuring Sign-In with Google ==

Google Sign-In Integration requires a Google Developer Project and API credentials. You can create this using your existing Google account. Users will only see the app name you define and will not see anything relating to the account you use to create the project.

To do this:

# Visit <tt>https://console.developers.google.com/</tt>.
# Log in to your Google account. <div class="docs-alert-warning">Changing the Google account you use to create the app requires users to reauthenticate and relink their accounts.</div>
# Choose '''Select a project''' on the top menu.<br/>[[File:Google-cloud-select-project.png]]<br/><br/>
# Choose '''New Project'''.<br/>[[File:Google-sign-in-2.png|600px]]<br/><br/>
# Enter a project name.<br/>[[File:Google-sign-in-3.png|600px]]<br/><br/>
# Click '''Create'''.
# Select '''Credentials''' in the left sidebar.
# Choose '''Create Credentials'''.<br/>[[File:Google-sign-in-5.png|600px]]<br/><br/>
# Select '''OAuth client ID'''.
# Click '''Configure Consent Screen'''.
# Select '''External'''.<br/>[[File:Google-sign-in-6.png|600px]]<br/><br/>
# Click '''Create'''.
# Add app information details.<br/>[[File:Google-sign-in-7.png|600px]]<br/><br/>
# Add an app domain.<br/>[[File:Google-sign-in-8.png|600px]]<br/><br/>
# Add authorised domains.<br/>[[File:Google-sign-in-9.png|600px]]<br/><br/>
# Add developer contact information.<br/>[[File:Google-sign-in-10.png|600px]]<br/><br/>
# Click '''Save and Continue'''.
# Select '''Credentials''' in the left sidebar.
# Choose '''Create Credentials'''.
# Select '''OAuth client ID'''.
# Choose '''Web Application'''.<br/>[[File:Google-sign-in-11.png|600px]]<br/><br/>
# Enter a name for your OAuth 2.0 client.
# Enter your full root domain in '''Authorized JavaScript origins'''.<br/>[[File:Google-sign-in-12.png|600px]]<br/><br/>
# Enter your full root domain in '''Authorized redirect URI'''.<br/>[[File:Google-sign-in-13.png|600px]]<br/><br/>
# Click '''Create'''.
# Save your client ID and secret, which you will use to activate Google Sign-In within WHMCS. <br/>[[File:Google-sign-in-14.png|600px]]<br/><br/>
# Log in to the WHMCS [[Admin Area]].
# Navigate to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Sign-In Integrations]]''' or, prior to WHMCS 8.0, '''Setup > Sign-In Integrations'''.
# Select '''Activate''' under the Google heading.
# Enter your Google Client ID and Client Secret.
# Click '''Save & Activate'''.

WHMCS will attempt to validate the details you have entered. If the client ID and secret are valid and successfully authenticate with the Google API, the values will be saved.

For troubleshooting help, see [[Troubleshooting Sign-In using Google]].

File:Signinintegrationslogin3.png

2023-10-24T13:58:45Z

PeterM:

File:Google-cloud-select-project.png

2023-10-24T13:56:08Z

PeterM:

File:Signinintegrationslogin2.png

2023-10-24T13:55:21Z

PeterM:

SolusVM

2023-10-19T11:11:56Z

PeterM:

== About this Module ==

[http://www.solusvm.com SolusVM] is a virtual server control panel from SolusLabs, Ltd. It supports OpenVZ virtualization (Linux), Xen virtualization (Linux, Windows, BSD), and KVM virtualization (Linux, Windows, BSD).

You can install two SolusVM modules:

* The '''Virtual Server Provisioning Module (Admin/Reseller)''' allows you to sell a range of virtual server products:
** You (the admin) can:
*** Create, destroy, suspend, unsuspend, upgrade, downgrade, reboot, boot, and shut down virtual servers.
*** Provision virtual servers in different locations.
** The client can:
*** Use functions and statistics from within the Client Area, including, reboot, boot, shut down, change passwords, change hostname, view resource usage and graphs, and use a serial console or VNC.
*** Order custom virtual servers.
* The '''Reseller Product Provisioning Module''' allows you to create a range of reseller resource products, allowing orders to auto-provison instantly on payment.

{{Provisioning_Module
| changepackage = Yes}}

== Adding a Virtual Server Provisioning Module (Admin/Reseller) Server ==

To set up a '''Virtual Server Provisioning Module (Admin/Reseller)''' server in WHMCS, you '''must''' [https://docs.solusvm.com/v1/solusvm-whmcs-billing-module/installation-and-configuration/Installation%2Bof%2Bthe%2Bmodule.html download the module] and install it according to SolusVM's instructions.

After installation, you can add and configure servers at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Servers]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Servers'''.

== Adding a Reseller Product Provisioning Module Server ==

To set up a '''Reseller Product Provisioning Module''' server in WHMCS, you '''must''' [https://docs.solusvm.com/v1/solusvm-whmcs-billing-module/installation-and-configuration/Installation%2Bof%2Bthe%2Bmodule.html download the module] and install it according to SolusVM's instructions.

After installation, you can add and configure servers at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Servers]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Servers'''.

== Creating a SolusVM Product ==

You can create a product that provisions accounts on your SolusVM server at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products_and_Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.

=== WHMCS Connect ===

This module does not support [[WHMCS Connect]].

==Troubleshooting==

''N/A''

{{modules}}

Payflow Pro

2023-09-27T10:05:54Z

PeterM: /* Adding the PayPal Pro Reference Payments Payment Gateway */

== About this Module ==

The Payflow Pro (PayPal) payment gateway module is available in WHMCS.
{{gateways
| type = cc
| onetime = yes
| recurring = yes
| refunds = yes
| 3dsecure = yes
}}
== Adding the Payflow Pro (PayPal) Payment Gateway ==

To set up the Payflow Pro (PayPal) payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''Payflow Pro (PayPal)'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Enter your Payflow Pro (PayPal) credentials.
#* '''Processor ID''', '''Merchant ID''', and '''Transaction PW''' are used by the 3D Secure process.
#** PayPal Pro accounts are enrolled for this by default. If you are enrolled, PayPal will provide details.
#** If they haven't or you don't want to use the 3D Secure feature, leave this information blank in WHMCS. This will disable the 3D Secure process and WHMCS will not use it during the checkout process.
#* To find your details for the Payflow Pro API:
#*# Log in to your PayPal account.[[File:Paypal_api.png‎|thumb|PayPal API]]
#*# Go to '''Account Setting''' by hovering over your name in the top-right corner.
#*# Click '''Update''' next to '''API Access'''.
#*# Under '''NVP/SOAP API integration''', click '''Manage API credentials'''.
#*# Choose '''Request API signature'''.
#*# Click '''Agree and Submit'''.
# Click '''Save Changes'''.

=== Test Mode ===

You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful to test your configuration.

==PayPal Pro Reference Payments==
<div class="docs-alert-warning">
This module does not support adding or updating card data via the Admin Area. Instead, admins can do this by paying an invoice on behalf of a client.
</div>
This gateway helps reduce your PCI compliance liability. Instead of storing card details, the ID of the last transaction is used to make repeat charges. If you use this, clients '''must''' reenter their card details to change payment gateways.
{{gateways
| level = 4
| type = token
| onetime = yes
| recurring = yes
| refunds = yes
| 3dsecure = yes
}}
=== Adding the PayPal Pro Reference Payments Payment Gateway ===

To set up this payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''PayPal Pro Reference Payments'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Enter your PayPal Pro Reference Payments credentials.
#* '''Processor ID''', '''Merchant ID''', and '''Transaction PW''' are used by the 3D Secure process.
#** PayPal Pro accounts are enrolled for this by default. If you are enrolled, PayPal will provide details.
#** If they haven't or you don't want to use the 3D Secure feature, leave this information blank in WHMCS. This will disable the 3D Secure process and WHMCS will not use it during the checkout process.
#* To find your details for the PayPal Pro API:
#*# Log in to your PayPal account.[[File:Paypal_api.png‎|thumb|PayPal API]]
#*# Go to '''Account Setting''' by hovering over your name in the top-right corner.
#*# Click '''Update''' next to '''API Access'''.
#*# Under '''NVP/SOAP API integration''', click '''Manage API credentials'''.
#*# Choose '''Request API signature'''.
#*# Click '''Agree and Submit'''.
# Click '''Save Changes'''.

== Troubleshooting ==

===Details could not be saved. Remote storage failed===

This message will display when attempting to create a credit card payment method via the Admin Area or Client Area. Due to restrictions in Payflow's ''Reference Payment'' features, this module does not support remote updating, storage, or deletion of card details.

Clients can specify a new card by viewing an invoice in the Client Area, clicking '''Pay Now''', selecting a new credit card, and providing the card's details.

===No Local Credit Card Payment Gateways Enabled===

You may encounter this error when attempting to make a payment via the Client Area if you have unchecked the option to save card details for later. Due to the reference nature of the gateway, the card details must always be stored at PayPal for automated rebilling of Reference Transactions to function.

The client's credit details will never be stored on your server.

{{modules}}

Payflow Pro

2023-09-27T10:03:38Z

PeterM: /* Adding the Payflow Pro (PayPal) Payment Gateway */

== About this Module ==

The Payflow Pro (PayPal) payment gateway module is available in WHMCS.
{{gateways
| type = cc
| onetime = yes
| recurring = yes
| refunds = yes
| 3dsecure = yes
}}
== Adding the Payflow Pro (PayPal) Payment Gateway ==

To set up the Payflow Pro (PayPal) payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''Payflow Pro (PayPal)'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Enter your Payflow Pro (PayPal) credentials.
#* '''Processor ID''', '''Merchant ID''', and '''Transaction PW''' are used by the 3D Secure process.
#** PayPal Pro accounts are enrolled for this by default. If you are enrolled, PayPal will provide details.
#** If they haven't or you don't want to use the 3D Secure feature, leave this information blank in WHMCS. This will disable the 3D Secure process and WHMCS will not use it during the checkout process.
#* To find your details for the Payflow Pro API:
#*# Log in to your PayPal account.[[File:Paypal_api.png‎|thumb|PayPal API]]
#*# Go to '''Account Setting''' by hovering over your name in the top-right corner.
#*# Click '''Update''' next to '''API Access'''.
#*# Under '''NVP/SOAP API integration''', click '''Manage API credentials'''.
#*# Choose '''Request API signature'''.
#*# Click '''Agree and Submit'''.
# Click '''Save Changes'''.

=== Test Mode ===

You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful to test your configuration.

==PayPal Pro Reference Payments==
<div class="docs-alert-warning">
This module does not support adding or updating card data via the Admin Area. Instead, admins can do this by paying an invoice on behalf of a client.
</div>
This gateway helps reduce your PCI compliance liability. Instead of storing card details, the ID of the last transaction is used to make repeat charges. If you use this, clients '''must''' reenter their card details to change payment gateways.
{{gateways
| level = 4
| type = token
| onetime = yes
| recurring = yes
| refunds = yes
| 3dsecure = yes
}}
=== Adding the PayPal Pro Reference Payments Payment Gateway ===

To set up this payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''PayPal Pro Reference Payments'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Enter your PayPal Pro Reference Payments credentials.
#* '''Processor ID''', '''Merchant ID''', and '''Transaction PW''' are used by the 3D Secure process.
#** PayPal Pro accounts are enrolled for this by default. If you are enrolled, PayPal will provide details.
#** If they haven't or you don't want to use the 3D Secure feature, leave this information blank in WHMCS. This will disable the 3D Secure process and WHMCS will not use it during the checkout process.
#* To find your details for the Payflow Pro API:
#*# Log in to PayPal.
#*# Go to '''Profile > My selling preferences > API Access'''. [[File:Pp_api2.png‎|thumb|PayPal API Step 2]]
#*# Choose '''Option 2''' to request API credentials to create your own API username and password.
#*# Choose '''Request API signature'''.
#*# Click '''Agree and Submit'''.
#*# Copy the provided username, password, and signature.
#*# Click '''Done'''.
# Click '''Save Changes'''.

== Troubleshooting ==

===Details could not be saved. Remote storage failed===

This message will display when attempting to create a credit card payment method via the Admin Area or Client Area. Due to restrictions in Payflow's ''Reference Payment'' features, this module does not support remote updating, storage, or deletion of card details.

Clients can specify a new card by viewing an invoice in the Client Area, clicking '''Pay Now''', selecting a new credit card, and providing the card's details.

===No Local Credit Card Payment Gateways Enabled===

You may encounter this error when attempting to make a payment via the Client Area if you have unchecked the option to save card details for later. Due to the reference nature of the gateway, the card details must always be stored at PayPal for automated rebilling of Reference Transactions to function.

The client's credit details will never be stored on your server.

{{modules}}

File:Paypal api.png

2023-09-27T09:59:47Z

PeterM:

Admin Dashboard

2023-09-20T09:15:27Z

PeterM: /* Widget Reference */

Each member of staff can personalise their admin dashboard view by minimising or hiding widgets, as well as rearranging via drag-and-drop (available in WHMCS 7.7 and later).

You will see the '''Admin Dashboard''' after you log in to the WHMCS [[Admin Area]].

[[File:82Dashboard.png|600px|thumb|The Admin Area Dashboard]]

== Dashboard Widgets ==

Widgets are the building blocks of the WHMCS Admin Dashboard. WHMCS includes a variety of dashboard widgets by default, which we design to give you an overview of activity and events occuring within your WHMCS installation.

<div class="docs-alert-info"><i class="fa fa-info-circle"></i> Looking for Site Widgets? The functionality that we previously referred to as site widgets is now [[Data Feeds]]. Data feeds allow you to fetch product and domain information for inclusion on custom site pages.</div>

== Managing Widgets ==

To move a dashboard widget, hover over the widget title. A cross-hair will appear. Click and hold to drag and reposition the widget. The system will display a target area where the widget will drop. Release the mouse to save the new position.

The system stores widget position preferences to your admin profile. Because of this, they will persist between admin login sessions and across all devices that you use to log in to WHMCS.

<div class="docs-alert-warning">
Due to differing widget sizes and the grid system layout, when moving a widget or reloading the page, other widgets may move automatically or reorder themselves to ensure optimum display. If you experience any overlapping of widgets, simply refresh the page.
</div>

=== Widget Controls ===

At the top right of each widget are the widget controls. These controls allow an admin user to customise their dashboard. The available actions include:

* '''Refresh''' — Refreshes the content of the widget. For performance reasons, many of the widgets cache their data for a period of time.
* '''Minimise''' — Minimises the widget. You can expand the minimised widget again later.
* '''Close''' — Closes the widget. This removes the widget from the dashboard for the current admin user. You must add it to the dashboard again to reopen it.

[[File:82WidgetList.png|300px|thumb]]

=== Showing/Hiding Widgets ===

You can manage widgets on the admin dashboard via the '''Show/Hide Widgets''' panel.

To open the panel, click the gear icon at the top-right of the dashboard.

Widgets with a check next to them are enabled and the system will render them on the dashboard. To remove a widget, uncheck the box next to its name. To add a previously removed widget, check the box next to its name. The dashboard will immediately update when you enable or disable a widget.

== Permissions ==

Widgets use the administrator role access control permissions system and therefore the widgets a user can see and has access to will match the user's permissions in the system.

For example, the Support Tickets widget will only show to a user with access to view and respond to support tickets.

<div class="docs-alert-warning">
Some older widgets do not leverage the access control permissions. You can control access to these individually via [[Administrator Roles]].
</div>

== Widget Reference ==

The following table itemises all widgets that WHMCS includes by default and their required permissions:

<table class="table table-bordered">
<tr>
<td>'''Name'''</td>
<td>'''Description'''</td>
<td>'''Required Permission'''</td>
</tr>
<tr>
<td>Activity</td>
<td>Recent system activity to keep you up to date with what's happening.</td>
<td>View Activity Log</td>
</tr>
<tr>
<td>Automation</td>
<td>An overview of system automation. Click a miniature graph to see a the full version on the [[Automation_Status|Automation Status]] page.</td>
<td>Configure Automation Settings</td>
</tr>
<tr>
<td>Billing</td>
<td>An overview of income over four periods: daily, monthly, yearly and all time.</td>
<td>View Income Totals</td>
</tr>
<tr>
<td>Client Activity</td>
<td>A brief overview of the last five client logins, including dates, times, and IP addresses.</td>
<td>List Clients</td>
</tr>
<tr>
<td>Health</td>
<td>An overview of System Health and links through the main [[System_Health_Status|System Health Status]] page.</td>
<td>Health and Updates</td>
</tr>
<td>MarketConnect</td>
<td>Provides details of the selling status of MarketConnect products with your current points balance and options to deposit funds and view promotions.</td>
<td>View MarketConnect Balance</td>
</tr>
<tr>
<tr>
<td>Network Status</td>
<td>Listing your servers and allowing you to check the status (if the system has implemented [[Servers#Status_Monitoring|status URL monitoring]]).</td>
<td>None</td>
</tr>
<tr>
<td>System Overview</td>
<td>An overview of orders and income in graphical format. You can change the timescale to show daily, monthly, or yearly orders and income.</td>
<td>View Income Totals</td>
</tr>
<tr>
<td>System Overview Badges</td>
<td>The colourful badges at the top of the page provide a quick statistical overview including orders, cancellation, and tickets.</td>
<td>None</td>
</tr>
<tr>
<td>Staff Online</td>
<td>Shows currently-logged-in staff. If the staff member's email address corresponds with a [https://gravatar.com/ Gravatar] account, the system will display the Gravatar image.</td>
<td>None</td>
</tr>
<tr>
<td>Stripe Balance</td>
<td>Displays the pending and available balances for the Stripe payment gateway.</td>
<td>View Gateway Balances</td>
</tr>
<tr>
<td>Support</td>
<td>An overview of support tickets that are awaiting replies, tickets that you assigned to your account, and tickets with recent activity.</td>
<td>List Support Tickets</td>
</tr>
<tr>
<td>To-Do List</td>
<td>An overview of support tickets that are awaiting replies, tickets that you assigned to your account, and tickets with recent activity.</td>
<td>To-Do List</td>
</tr>
</table>

== Creating Widgets ==

Addon and third party module developers can also include dashboard widgets as part of a custom module. For information on creating your own widgets, see our [https://developers.whmcs.com/addon-modules/admin-dashboard-widgets/ Developer Documentation].

== Troubleshooting ==

=== Oops Error ===

An Oops Error Message is shown when viewing the Dashboard.
This can be caused by an incompatible widget. Please follow our guide on blank/oops pages to obtain the full error - https://help.whmcs.com/m/troubleshooting/l/678235-troubleshooting-a-blank-page-oops-error-message.
The error will reference the widget that is causing the failure. Once you know the affected widget you can remove the files from '''/modules/widgets/''' or obtain an updated version of from the developer.

=== Blank Dashboard After Update ===

If none of the admin dashboard widgets are loading following an update of WHMCS, then the problem most likely lies in the table collation values.

For more information, see [https://help.whmcs.com/m/updating/l/1040457-troubleshooting-a-blank-admin-dashboard-after-update Troubleshooting a Blank Admin Dashboard After Update].

PayPal Basic

2023-09-20T09:01:41Z

PeterM: /* Adding the PayPal Basic Payment Gateway */

== About this Module ==

<div class="docs-alert-info"><i class="fa fa-info-circle"></i> In previous versions, the '''PayPal Basic''' module was the '''PayPal''' module. For information on the newest PayPal module, see '''[[PayPal Checkout]]'''.
</div>

The PayPal Basic payment gateway module is available in WHMCS.
{{gateways
| onetime = yes
| recurring = yes
| refunds = yes
| reversals = yes
}}

== Adding the PayPal Basic Payment Gateway ==

<html><a href="https://www.youtube.com/watch?v=L0B6KbPaGKE&hd=1" class="docs-video-tutorial"><em>Watch the video tutorial for this feature</em><span> <img src="https://assets.whmcs.com/icons/youtube.png"> </span></a></html>

To set up the PayPal Basic payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''PayPal Basic'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Enter your PayPal Basic credentials.
## For '''PayPal Email''', enter the email address associated with your PayPal account, this is the only required field and all others are optional. If you have more than one email address associated with your PayPal account, you may add as many of those as you like, comma-delimited. You must next configure [[#Instant_Payment_Notification_.28IPN.29|Instant Payment Notifications]].
## For '''Force One Time Payments''', check to only allow clients to make one-time payments (subscriptions disabled). For recurring services they will be required to login and pay each invoice.
## For '''Force Subscriptions''', check to only allow clients to make subscription payments when applicable (one-time payments disabled). This means future payments will be sent automatically without the need for manual intervention. There are some [[#PayPal_Subscriptions.2FRecurring_Billing|caveats explained below]].
## For '''Require Shipping Address''', check to require clients to provide a shipping address on the PayPal website and will be associated with their payment at PayPal, useful when selling physical products and for PayPal's Seller Protection.
## For '''Client Address Matching''', check to ensure that the details the client provides in WHMCS upon ordering will be used associated with their payment at PayPal. They will not be given the opportunity to provide different details on the PayPal website. Clients can update their profile via the WHMCS client area or your staff can use the '''Profile''' tab.
## For '''API Username''', '''API Password''', and '''API Signature''', enter the credentials from your PayPal account:
### Log in to your PayPal account.
### Go to '''Account Setting''' by hovering over your name in the top-right corner.
### Click '''Update''' next to '''API Access'''.
### Under '''NVP/SOAP API integration''', click '''Manage API credentials'''.
### Choose '''Request API signature'''.
### Click '''Agree and Submit'''.
##* This allows you to issue refunds from within WHMCS instead of logging in via PayPal.
##* For more information refer to [[#Automated_Refunds|Automated Refunds]]
# Click '''Save Changes'''.

=== Sandbox Mode ===

You can use test mode to simulate payment processing without actually causing a transaction to occur. It does this by connecting to PayPal's sandbox environment. This can be useful to test your configuration.

* To use this, you must create a [https://developer.paypal.com/ PayPal sandbox account].
* If your sandbox API credentials differ from your live account's, you must update them in your configuration and reset them when you finish testing.

==Instant Payment Notification (IPN)==

[[File:paypalcharsetnew.png|thumb|PayPal IPN Setup]]

For PayPal invoices to be automatically marked paid when you receive a payment you need to enable IPN inside your PayPal account.

# Log in to your PayPal account.
# Click the settings icon (usually your name) at the top of your PayPal account page.
# Click '''Account Settings'''.
# Select '''Notifications''' on the left-hand menu.
# Click the '''Update''' link for the '''Instant Payment Notifications''' item.
# Click '''Choose IPN Settings''' (or '''Edit Settings''' if it is already enabled).
# Enter in your WHMCS System URL (e.g. https://www.example.com/whmcspath/).
# Select the '''Receive IPN messages (Enabled)''' option.
# Click '''Save'''.

===Charset Configuration===

[[File:paypalcharset.png|thumb|PayPal Charset Configuration]]

PayPal defaults the charset used for most accounts to windows-1252. Whilst this is acceptable and will not cause an issue for most users, on occasion, accented characters can be returned incorrectly through the IPN causing the IPN Handshake Invalid message. Setting the charset in your PayPal account to match your WHMCS installation is a recommended setting to ensure this issue does not occur. The default value is '''UTF-8'''.

This is done via the '''Language Encoding''' page https://www.paypal.com/cgi-bin/customerprofileweb?cmd=_profile-language-encoding. Once here, click on '''More Options''' and choose your charset from the dropdown and ensure the radio option is set to '''Yes'''. Click on '''Save''' and your configuration is completed.

==PayPal Subscriptions/Recurring Billing==

Unless disabled in the PayPal gateway config, when a user views an invoice for a recurring product or service they will be shown a PayPal Subscribe button. This allows the user to subscribe so that their payment for that product or service is sent to you automatically each month/quarter/etc... and automatically applied to the appropriate renewal invoices by WHMCS.

There are three conditions that must be met for the PayPal subscribe button to appear:

# The invoice's Due Date must be in the future
# The invoice must contain at least 1 recurring product (ie. domains, billable items or addons on their own won't create subscriptions)
# The 'Force One Time Payments' option is UNticked on the payment gateway configuration page.

If an invoice contains both a product, and addons or domains, then any which '''match the products''' billing cycle will '''also be included''' as part of the subscription. For example, if an invoice contained a product, an addon & a domain, all of which recur on an annual basis, then the PayPal subscription that gets created by WHMCS would be for the total amount of all 3 items so that the '''subscription would cover everything''' and pay the renewal invoice in full automatically. What isn't possible however is to create a subscription that has different amounts recurring on different recurring terms, ie. $x Monthly + $Y Annually. PayPal doesn't offer an option for that at the current time.

===Customising Invoice Emails for Subscriptions===

When a subscription is created, the Subscription ID number that gets issued by PayPal is stored by WHMCS in the Subscription ID field for the product. Similarly when a subscription is cancelled the Subscription ID gets removed again. Therefore it is possible to use that ID value to determine if a subscription exists and therefore customise the text shown to the customer in the invoice related emails based on that.

For example, one might customise the "Invoice Created" email template to show different instructions to the customer if a subscription exists (meaning no manual action is required), compared with if one doesn't (meaning the client needs to login and pay the invoice manually), for example:

{if $invoice_subscription_id}
As you have a PayPal Subscription setup, payment will be taken automatically within the
next few days. Please ensure you have enough funds in your PayPal account to cover it.
{else}
You can login to your client area to view and pay the invoice at {$invoice_link}
{/if}

===Automatic Subscription Management===

If the Automatic Subscription Management feature is enabled on the installation, then WHMCS will attempt to automatically cancel PayPal subscriptions where applicable.

For details regarding the Automatic Subscription Management feature please refer to the [[Invoice_Tab#Automatic_Subscription_Management|Configuration]] section of the documentation.

==Automated Refunds==

You can issue refunds for PayPal payments directly from within WHMCS. Before you can do this however, you need to setup PayPal API access. The steps for doing this are as follows:

[[File:PP_API1_rev2.png‎|thumb|PayPal API Step 1]]
[[File:PP_API2_rev2.png‎|thumb|PayPal API Step 2]]
*Login to PayPal
*Go to '''Tools > All Tools > API credentials > NVP/SOAP API integration (Classic)'''
*Click '''Manage API Credentials''' - under the "NVP/SOAP API integration (Classic)" heading
* From there, you can generate a new set of credentials, view the current credentials, or remove them and create a new set
*Copy the username, password and signature that get provided and then click Done
*Enter the details from the previous step into the WHMCS Payment Gateways config screen where requested

You will now be able to enter a refund and have it sent from PayPal at the same time from within the WHMCS admin area invoice management screen.

== Troubleshooting ==

===Invalid Receiver Email===
WHMCS validates the payment receiver email value against the details specified under '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways''', so this error means the two do not match. If multiple PayPal accounts are used to receive payment, or a single PayPal account has multiple email addresses associated with it ,they must all be listed in a comma separated list eg. email1@mycompany.com,email2@mycompany.com.

The first email you specify will then be the email used for new payments, but any email in the field will be accepted as an invoice payment.

===Not Supported===
This Result will appear when an action occurs that does not require any action on WHMCS' behalf, for example a txn_type value of "subscr_failed" mean a subscription payment failed or "subscr_eot" means End of Subscription Term. You will see these entries under normal operation and is not a problem.

===Unrecognised Currency===
This error in the Gateway Log means an invalid currency code has been entered under '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''. A currency code must use the ISO 4217 standard as explained on the [[Currencies]] page. For example EURO is not valid, but EUR is valid.

This could also be caused by a blank space at the beginning or end of the currency code, so edit the code to ensure there are none.

===IPN Handshake Invalid===
Getting this message in your Gateway Log would mean that WHMCS is unable to verify that the callback occurring has come from PayPal.
This is to stop any false payments being applied to your account, however, on occasion, some valid payments can generate this error.
Follow the instructions above for setting the [[#Charset_Configuration|Charset]] of your IPN to stop this.

===IPN Handshake Error===
Getting this message in your Gateway Log indicates that whilst the IPN from PayPal was received, WHMCS was unable to verify the IPN data. The verification process involves connecting to PayPal's callback verification service at https://www.paypal.com/cgi-bin/webscr. This error will be observed if that connection fails. It can fail if the cURL connection made does not use the required protocols, transport Layer Security version 1.2 (TLS 1.2) and Hypertext Transfer Protocol version 1.1 (HTTP/1.1) are mandatory for communication with PayPal.

The WHMCS PayPal module does not specify a particular cryptographic protocol when communicating with PayPal. This means that cURL on your server should automatically negotiate the best protocol to use. Should you encounter the error above, it means your server is trying to negotiate a secure connection using one of the cryptographic protocols that PayPal no longer support. In that situation it would be necessary to work with your system administrator to ensure TLS 1.2 or greater is the default protocol on the server.

If the cURL test response is successful, it would be necessary to check a successful connection to PayPal's callback verification service at https://www.paypal.com/cgi-bin/webscr can be made.

This can again be checked using cURL from your servers command line, for example:

<source lang="php">curl -I https://www.paypal.com/cgi-bin/webscr</source>

Any errors shown can again be referred to your server administrator to review and resolve.

===Things don't appear to be working at the moment===
Upon reaching the PayPal website, the error is displayed '''Things don't appear to be working at the moment. Please try again later'''.

This message indicates invalid details being sent to PayPal. It could be invalid client details (eg. address, postcode) or a misconfiguration in the WHMCS settings (eg. an invalid currency code - it should be a three letter ISO-4217 format from [https://developer.paypal.com/docs/nvp-soap-api/currency-codes/#paypal PayPal API's supported currency list]).

Return to the client area invoice, view the page source and examine the PayPal payment button HTML code. Look for any variables which could be invalid. Then edit the client's profile or system settings to correct it.

If the currency_code value is not amongst [https://developer.paypal.com/docs/nvp-soap-api/currency-codes/#paypal PayPal API's supported currency list] then the [[Payment_Gateways#Setting_Up_Gateway_Modules|Convert to For Processing setting]] can be used to transparently convert the payment amounts into a currency which is supported by PayPal.

{{modules}}

Clients:Summary Tab

2023-09-12T14:04:31Z

PeterM: /* Invoices/Billing */

{{Client Management}}

The '''Summary''' tab contains an overview of the client's details, billing and service statistics, quick links to many common management actions, and a list of all their services, domains, and addons.

You can access this tab when you view a client's profile at '''Clients > [[Client Management|View/Search Clients]]'''.

[[File:82ClientSummary.png|thumb|Client Summary Tab]]

==Summary Actions==

The top-left corner of the page displays the client's unique ID number and name. To the right, summary actions allow you to manage billing-related settings.

Click the click '''Yes''' (green) or '''No''' (red) to instantly toggle the status of these options:

* '''Exempt From Tax''' — Do not charge tax, even if the client has a tax rule.
* '''Auto CC Processing''' — Automatically charge the client's stored credit card on invoice due dates.
* '''Send Overdue Reminders''' — Send overdue reminder emails when the client's invoices become overdue.
* '''Apply Late Fees''' — Charge a late fee when the client's invoices become overdue. <div class="docs-alert-warning"><span class="title">Late Fees</span><br/>You must activate and configure late fees in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings''' and in the '''[[Invoice Tab|Invoice]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.</div>

==Client's Information==

This section displays the client's contact information and the '''Reset & Send Password''' and '''Login as Owner''' links.

=== Phone Numbers ===

In WHMCS 7.4 and later, you can easily enter and store international phone numbers.

[[File:PhoneNumberInputUx.png|500px]]

This system ensures a consistent and uniform phone number format combining the country prefix and phone number:

+ '''[Country Code]''' . '''[Phone Number]'''

In WHMCS 7.4 and later, this feature is enabled by default. The system will save the client's phone number in the database and automatically prefix it with the international country dialing code.

To disable this, uncheck '''Phone Numbers''' in the '''[[Localisation Tab|Localisation]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. When you disable this feature, the system will not add the prefix in the database but will display it in the Admin Area and Client Area.

====Automatic Number Formatting====

The pre-selected country will default to your WHMCS system default country. The system will update the selected country whenever you change the client's physical address. This change will occur even if the phone number is currently empty.

Users can also begin typing a phone number that begins with a country code in the format <tt>+XX</tt> and the system will update the country.

The update process will automatically convert existing client phone numbers when they display in a phone number field. The phone number value will update in the database the first time that an admin or client saves the phone number.

====Order Forms====

For example:

[[File:PhoneNumberOrderForm.png|500px]]

===Reset & Send Password===

Click to generate a new Client Area password for the client and email it to them.

Clients can also request a password reset by clicking '''Forgotten Password''' on the login form. After entering their email address, if there is a set security question and answer, the system will prompt them to supply the answer. Then, they will receive an email with a confirmation link, to ensure that they are the person who requested the password reset. The link is valid for two hours from the time of request.

* If there is not a set security question and answer, the system sends the email immediately when the client enters their email address.
* When they click the link in the email, clients will go to the password reset validation page, from which they can set a new password. They can then log in immediately using the new password. If the client didn't request the reset, they can ignore the email.

<div class="docs-alert-warning">
<span class="title">WHMCS 8.0 and later</span><br />
To reset the user's password in WHMCS 8.0 and later, use the client profile '''[[Clients:Users_Tab#Password_Reset|Users]]''' tab.
</div>

===Login as Owner===

Click to view the Client Area exactly as the account's owner would see it. Clicking the linked text will open the Client Area in your current tab, or you can click the window icon to open the Client Area in a new tab.

When you access the Client Area in this way, you can also perform actions on the account owner's behalf, like placing orders or opening tickets. When you are finished, click '''Return to Admin Area''' in the top-right corner to return to the Admin Area.

<div class="docs-alert-warning">
Prior to WHMCS 8.0, this was '''Login as Client'''.
</div>

==Contacts/Sub-Accounts==

This section lists the client's contacts or sub-accounts. Click a name to edit that record in the '''[[Clients:Contacts_Tab|Contacts]]''' tab.

===Add Contact===

Click to create a new contact or sub-account for this client.

==Pay Methods==

Displays an overview of the client's current registered payment methods in WHMCS.

The default Pay Method will always be displayed at the top of the list, and be indicated via an icon.

===Adding a Pay Method===

You can add a new payment method by clicking '''Add Credit Card''' or '''Add Bank Account'''. These links are only available when there is an appropriate activated module.

<div class="docs-alert-info">
These options will only display if you have activated an appropriate [[Payment Gateways|payment gateway]]. If you do not have either an active merchant gateway and/or bank account module, then no options to add payment methods will be displayed.
</div>

When multiple payment gateways are active, and include a combination of both local card storage and tokenized payment gateway modules, upon selecting to add a credit card, you will be prompted for the storage method you wish to use. Essentially, you need to tell WHMCS if the card should be tokenized with your desired payment gateway, or stored locally and encrypted in the database. In most cases if you have a tokenization payment gateway in use, you will probably want to use this.

===Managing Pay Methods===

You can manage a pay method by clicking on it in the list.

====View Locally-Stored Credit Card Numbers====

To view the associated locally-stored credit card number (local encryption), click the lock icon and enter your Credit Card Encryption hash (in <tt>configuration.php</tt>).

For tokenisation gateways, viewing the full card number is not possible because WHMCS does not store the details. You can only view the respective token and the last four digits of the card number.

====Removing Card Details====

Click '''Delete''' to remove the card's details from the client and WHMCS.

If an error occurs deleting a remote [[Pay Methods|payment method]], or if the gateway that a remote payment method is associated with has been deactivated, WHMCS will be unable to delete the record. When this happens, a message will be shown displaying the error that occurred and providing an option to ignore and force delete the payment method.
[[File:PayMethodDeleteFail.png]]

Forcibly deleting a payment method will not run anything on the remote gateway system. Manual removal of any records in a gateway account would need to be done manually if required, when force deleting from WHMCS.

==Invoices/Billing==

In this section quick invoice and billing statistics are displayed; the number of invoices in each status along with the total value of each in brackets:

* '''Paid''' — The number of invoices and their total invoice amount in the ''Paid'' status.
* '''Draft''' — The number of invoices and their total invoice amount in the ''Draft'' status.
* '''Unpaid/Due''' — The number of invoices and the total amount due in the ''Unpaid'' status. The total is the outstanding amount of the invoices.
* '''Cancelled''' — The number of invoices and their total invoice amount in the ''Cancelled'' status. The total does not include any payments that the client has already made.
* '''Refunded''' — The number of invoices and their total invoice amount in the ''Refunded'' status. The total does not include any payments that the client has already made.
* '''Collections''' — The number of invoices and their total invoice amount in the ''Collections'' status. The total does not include any payments that the client has already made.

In the Income sub-section, the statistics are calculated as follows:

* Gross Revenue statistic shows the total of all transactions paid by the client
* Client Expenses is the sum of transaction fees and refunded transactions
* Net Income is the Gross Revenue - Client Expenses
* Credit Balance shows the current amount of credit available to the client to spend

===Create Invoice===

Click '''Create Invoice''' to create a custom invoice. This immediately creates an empty invoice that you can add line items to. Clicking will not send an email to the client.

For steps for the remaining process of adding a custom invoice, see [[Invoicing]].

===Create Add Funds Invoice===

You can create invoices in this way to allow a client to deposit funds to their account, or to charge a specific amount from a clients credit card. A popup will appear allowing the amount of credit to be specified. The customer will receive an email for the invoice that the system generated with a link to pay it.

For more information, see [[Add Funds]] and [[Invoicing]].

===Generate Due Invoices===

Click here to generate any invoices due for the client's services, billable items, domains or addons. Useful if one of the aforementioned items has been modified and a new invoices needs to be generated without the need to run the entire automation cron job. A popup will appear asking whether you wish to send the invoice notification email.

===Add Billable Item===

This link will take you directly to the Add Billable Item interface. For more information, see [[Billable Items]].

===Manage Credits===

Displays a popup displaying the client's credit history; how credits were earned and spent. Credit can also be manually added and removed using the appropriate buttons. You also have the option to delete entries if you wish and they will then be deducted from the credit balance.

For more information, see [[Transactions#Managing_Credit|Managing Credit]].

==Create New Quote==

This link will take you directly to the Quote creation interface. For more information, see [[Quotes]].

==Other Information==

In this section, miscellaneous information is displayed; the client's status, their client group, signup date, length of time since signup and the IP address, hostname, and time of their last login.

==Products/Services==

In this section the numbers all the services, domains quotes, support tickets and affiliate signups for this client are displayed. The active service count is displayed first, with the total - including services in suspended, terminated and cancelled statuses - in brackets.

===View Orders===

Click this link to see a list of all orders placed by this client. For more information, see [[Order Management]].

===Add New Order===

This link will take you to the admin order form. This allows orders to be placed on behalf of the client, and for products and promotional codes to be used in combinations not possible on the public order form.

==Files==

The files section in a client's summary allows you to upload files specific to that customer.

* This can be used for documents, agreements or other downloads specific to the individual
* Files can be set as Admin Only to only be viewed by admins, otherwise they show on the Client Area homepage for the client to be able to download
* Files are uploaded to the /attachments directory and can be added and managed from the client profile '''[[Clients:Summary Tab|Summary]]''' tab in the Admin Area.

==Recent Emails==

Displayed here are the last five emails sent to the client by WHMCS. You can view a longer email history in the client profile '''[[Clients:Emails Tab|Emails]]''' tab.

==Other Actions==

Within this section are a number of miscellaneous links which perform a variety of tasks.

===View Account Statement===

This displays a statement of account for this client accounts between a date range. It includes the type (add funds, transaction, invoice), date, description, credits, debits, and a running balance.

===Open New Support Ticket===

This link enables you to open a support ticket under the client's account. This is useful for initiating correspondence with the client and keeping a full record of the conversation.

===View all Support Tickets===

Click here to see see a list of all support tickets assigned to the client in the departments to which your administrator account is assigned. If the client had tickets in departments of which you are not a member, they would not be displayed here.

===Activate as Affiliate===

If enabled clients can join the affiliate program from within the client area. Staff members can also add the client to the affiliate program by clicking this link.

===View Affiliate Details===

Once the client has been activated as an affiliate, the 'View Affiliate Details' link will be displayed in its place. Click it to see the client's referrals, commissions pending and paid, as well as your payments to them. For more information, see [[Affiliates]].

===Merge Client Accounts===

Merging clients combines two separate client accounts in WHMCS into one. This merges everything relating to the two separate entities into one including but not limited to products, invoices, transactions, or tickets.

[[File:Merge clients.png|thumb|Merge Clients Popup]]

To do this:

# Go to the client profile for the first client that you want to merge.
# Click '''Merge Client Accounts'''.
# Enter the other client's client ID. If you don't know the client's ID, enter their name, company or email address in the '''Search''' field. Click the client's name and the system will automatically fill in the ID.
# Choose which profile you want to keep (the client you want to merge the other client's data into).
# Click '''Submit'''.

===Close Clients Account===

Closing a client's account will prevent them from being able to log in to the client area. This link will also change the status of unpaid invoices to cancelled, and all services to cancelled. It will not run any module termination functions.

===Delete Clients Account===

To remove a client, click this link. If you also want to remove any associated users that aren't associated with other client accounts, check the checkbox. Then, confirm the deletion. The client will be removed and you will be returned to the '''Clients''' list.

Deleting a client removes everything related to that client from the WHMCS database, with the exception of transactions. This is because transactions are considered income that isn't being refunded when the client is removed. If you want to also remove the client's transactions, do this in the '''[[Clients:Transactions Tab|Transactions]]''' tab before you delete the client.

===Export Client Data===

Click to go to the '''Client Data Export''' report at '''Reports > More...'''. The system will preselect the current client. From this report, you can download selected client data as a <tt>.json</tt> file.

For more information, see [[Reports#Client|Reports]].

==Send Email==

Use this menu to send email to clients. You can send '''General''' email templates or compose custom messages for the individual client.

To send a client-related email message using an existing email template, select that template from '''Send Email''' and click '''Send'''.

For custom emails:

# Select '''New Message''' from '''Send Email'''.
# Click '''Send'''.
# Compose your message.
# If you want to use the message again in the future, check '''Save Message'''.
# Click '''Send Message'''.

For more information, see [[Messages/Emails]].

==Admin Notes==

Here staff can enter private notes about the client.

Separate notes sections are available under the '''[[Clients:Products/Services Tab|Products/Services]]''', '''[[Clients:Domains Tab|Domains]]''', and '''[[Clients:Notes Tab|Notes]]''' tabs.

==Filtering Products==

[[File:filtering_products.png|thumb|Product Filtering]]

There may be situations in which it's desirable to filter the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab to only display items in certain statuses. For example, if a client has a large number of old cancelled services, you may wish to only display the active, pending, and fraudulent products, hiding the cancelled ones.

To do this, click '''Status Filter''' under the '''Admin Notes''' section. A prompt will appear allowing you to select which statuses to display.

* After the filter is applied, the button will be green.
* This filter will apply across all clients until you close the browser.

==Services, Addon, Domains, Quotes==

The '''Services''', '''Addons''', '''Domains''', and '''Quotes''' lists provide a comprehensive list of all the client's services and include information like the price, signup date, status, and next due date.

The lists are ordered based upon the item's ID number. Click the ID number of the '''Edit icon''' to see the full details of the item from where you can make changes.

The '''Current Quotes''' section displays quotes with a '''Valid Until Date''' up to and including today's date. After this date, you can view them in the '''[[Clients:Quotes_Tab|Quotes]]''' tab.

==Mass Updating Services/Addons/Domains==

[[File:Bulk_actions_panel.png|thumb|Mass Update Panel]]

The mass update options enable you to make changes to more than one of a given clients products, add-ons and domains at a time. This is useful for making bulk changes to a clients products and services.

Supported fields you can change in a mass update include:

* Status
* Payment Method
* Override Auto-Suspend
* Pricing
* Billing Cycle
* Next Due Date

You can also perform all the core module commands:

* '''Create'''
* '''Suspend'''
* '''Unsuspend'''
* '''Terminate'''
* '''Change Package'''
* '''Change Password'''

To use the feature, follow the steps below:

# Check the checkboxes next to the products, services, addons, and domains you want to update.
# Under '''Bulk Actions''', click '''Advanced Options'''.
# Make your changes and selections. Leave any fields that you don't wish to change blank.
# Click '''Apply'''.

===Due Date Changes Prorata Calculation===

When making a change to the '''Next Due Date''' of products and services, you also have the option to bill for the days between the current next due date and the target next due date you set. This is useful for synchronising multiple different products to a single common due date each billing cycle.

To do this, follow the steps below:

# Check the checkboxes next to the products, services, addons, and domains you want to update.
# Under '''Bulk Actions''', click '''Advanced Options'''.
# Enter the desired '''Next Due Date'''.
# Check '''Create Prorata Invoice'''.
# Click '''Apply'''.

The page will reload with confirmation of the changes and that an invoice has been generated.

<div class="docs-alert-info">
An invoice will only be generated if the differences for all products result in an amount being due. If the total differences result in a credit then no invoice will be generated and no credit will be issued.

To add a credit for the difference, see [[Credit/Prefunding#Adding_Credit_to_a_Client|Credit/Prefunding]].
</div>

==Invoice Selected Items==

<div class="docs-alert-info">
In WHMCS 8.8 and later, you can enable and configure on-demand renewals to allow customers to renew services early, before invoice generation, from within the Client Area. For more information, see [[On-Demand Renewals]].
</div>

There may be times where a client asks for you to invoice them for the next renewal date early. To do this, check the checkboxes for the desired products, services, addons, and domains and then click '''Invoice Selected Items'''.

* This may create multiple invoices if the due dates and payment methods differ. This is because this process continues to obey the usual invoicing rules.
* You cannot generate another invoice if an invoice has already been made for the next due date.

If you select multiple items with the same '''Next Due Date''' and '''Separate Invoices''' is enabled in the client's profile or [[Client Groups|client group]], it will not apply and all possible items will be invoiced together. To split them, edit the resulting invoices and use the '''Split Invoice''' function.

==Delete Selected Items==

Check the checkboxes next to the services, domains, addons, or quotes that you wish to remove and click '''Delete Selected Items''' to delete multiple items at the same time.

This will remove the record from WHMCS but will not trigger any module commands (for example, the hosting account for a service will stay on the server).

Promotions

2023-08-15T13:41:59Z

PeterM: /* How to create a new promotion */

Promotions can offer discounts on your products and services, product addons, and domains.

You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Promotions''' or, prior to WHMCS 8.0, '''Setup > Payments > Promotions'''

For information on setting up commonly-used promotions, see [[Common Promotions]].

==Types of promotions that can be offered==

*One Time Discounts
*Recurring Discounts
*Limited Recurring Discounts (for example, first two months free)
*Monetary Discounts (for example, $5 Off)
*Percentage Discounts (for example, 20% Off)
*Price Override (for example, Regular price $10, Discount price $8)
*Free Setup
*Apply to Specific Products/Addons/Domain TLDs
*Apply to Specific Billing Cycles or Registration Periods
*Apply Once per Order or to All Applicable Items in Cart
*Lifetime Promotion
*Valid for New Signups Only
*Valid for upgrade orders only

==How to create a new promotion==

To create a new promotion:

# Click '''Add New''' at the top of the page.
# Enter a promotion code. This is the code that customers will need to enter on the order form to receive the discount.
# Choose one of the four promotion types:
#* Percentage — Discount by a percentage of the original price.
#* Fixed Amount — Discount a specified amount from the original price.
#* Price Override — Changes the product price to this value. Use this to offer a consistent discount across multiple billing cycles.
#* Free Setup — Discount any setup fee from the original price.
# To have the discount only apply to the first invoice, do not check '''Recurring'''.
#* When you check this, the discount will apply to renewal invoices.
#* Set '''Recur For''' to <tt>0</tt> for all future renewals to discount, or enter a different number to specify how many cycles the discount lasts for. This is in addition to the initial invoice for the product. If you wish to provide a discount 6 times, enter <tt>5</tt> in the recurring box.
# For '''Value''', enter the amount of the discount in positive numbers (up to 2 decimals) only.
# Select the products, addons, and domain TLDs that the promotion applies to and what billing cycles or registration periods the discount requires. These should match those of your products. Your can press <tt>Ctrl+click</tt> to select multiple entries.
# Optionally, set the start and expiration dates. If you use one or both of these settings, the coupon will only start working after the start date and will stop working at expiration.
# Use the following checkboxes to specify who can use the promotion:
#* Apply Once — If the client orders multiple qualifying products, the system only applies the discount once.
#* New Signups — Only new clients can use the promotion.
#* Apply Once / Client — If a client has an existing active order that uses this promotion, they will not be able to use the code a second time.
#* Lifetime Promotion — Client will retain this discount even if they upgrade or downgrade their service in future, regardless of settings such as maximum uses or expiration date.
#* Existing Client — Only existing clients with one or more active orders can use the promotion.
#* Enable for product upgrades – See [[#Upgrades/Downgrades|Upgrades/Downgrades]] below.
# In the admin notes section, add information that admins may need about the promotion.

The promotional code changes the '''First Payment Amount''' when a customer or administrator uses the code when ordering. For recurring promotions, the code will also change the '''Recurring Amount'''. The system will set the '''Recurring Amount''' to the final amount to bill the client after taking the promotion into consideration. For promotional codes that recur for a set number of billing cycles, the '''Recurring Amount''' will automatically revert to the full price after that time.

==Limiting Usage==

You can set the maximum number of times to honor a promotion. To do this:

# Locate the promotion you want to limit the usage of and click the edit icon next to it.
# For '''Maximum Uses''', enter the number of uses that you want to allow.
#* The number of times that customers have used the promotion will display below this setting.
#* For unlimited uses, enter <tt>0</tt>.
# Click '''Save Changes'''.

==Prerequisites==

By selecting products from '''Requires''', you can stipulate which products or services the client must also have in their shopping cart before applying the discount. You can use this to offer "buy x get y half price" promotions.

'''Also allow existing products in account to qualify for promotion''' allows the system to include active products that the client already owns in the promotion criteria.

For example, if the client already owns product x with an '''Active''' service status, they would be able to use the promotion code when ordering product y. If you disable this option, the client would need to order both products x and y at the same time to qualify.

==Upgrades/Downgrades==

When you check this checkbox, the client will use the promo code when placing an upgrade or downgrade order, which is particularly useful for offering incentives when upselling. When you check this, some new options will appear:

===Products/Services===

Select ''Products/Services'' as the '''Upgrade Type'''.

Use '''Type''', '''Recurring''', and '''Value''' fields to specify the value of the discount and how long it lasts.

Use '''Applies To''' to select which products to apply the promotional code to. The client will receive the discount when upgrading to this product.

For upgrades and downgrades, use '''Requires''' slightly differently. It restricts which products clients can upgrade. For example, they can upgrade from a selected product to this product and receive a discount, but not upgrade from an unselected product and receive a discount.

===Configurable Options===

To offer discounts to clients for configurable options, select ''Configurable Options'' as the '''Upgrade Type'''.

Use '''Upgrade Discount''' to specify the discount value as a percentage or fixed amount for the configurable options. Then, use '''Config Options Upgrades''' to select which option this discount applies to.

If you use the main '''Type''', '''Recurring''', and '''Value''' at the top of the page, the system will apply a discount to the parent product as well as to the configurable option. Leave this blank to only apply the discount to the configurable option.

==Promotion Links==

You can give links to users that will automatically apply a certain promotion code to their order if it applies. To do that, use a link like the one below:

cart.php?promocode=TEST '''OR''' cart.php?a=add&pid=1&promocode=TEST

Both of the above will apply the promotion code <tt>TEST</tt> to the order. With the first link, the user can choose the package they want. With the second, they will go straight to step 2 of the order process with product ID <tt>1</tt> selected.

For more information, see [[Linking to WHMCS]].

==Management==

When you create a promotion, you can specify an expiry date. If you want the promotion code to become invalid before this date, click '''Expire Now'''.

You can create a copy of any promotion by clicking '''Duplicate Promotion'''. This is particularly useful for quickly running a successful promotion again or providing a personalised promo code to a client.

==Manually Applying a Promotion==

WHMCS allows you to manually add a promotion code to an existing service. You can make this type of addition when viewing a client’s existing service in the Admin Area.

Click '''Promotion Code''' for a list of all the active promotions on the installation. From this list, you can select the promotion you would like to apply to the service, and then click '''Save Changes''' to commit your changes.

'''Recurring Amount''' on the service page is the final amount to bill the client for after taking the selected promotion into consideration. Selecting a promotion code by itself will not change the invoice amount.

Due to this behavior, it is important to update '''Recurring Amount''' so that it reflects the amount you want the customer to pay after applying the promotion code. You can do this in one of two ways:

* Manually calculate the amount that you would like the customer to pay after the discount and enter it in '''Recurring Amount'''. Then, click '''Save Changes'''.
* Select '''Auto Recalculate on Save''', and then click '''Save Changes'''. This option will have WHMCS take the current pricing for the product or service, apply the discount from the selected promotion code, and then set '''Recurring Amount''' for that value.

For client services with a promotion code, WHMCS alters how it generates the service’s invoice items for renewal invoices.

To provide the client with information concerning discounts from promotion codes, WHMCS will generate two invoice items. The first item will display the sum of '''Recurring Amount''' and the discount amount. The second item will display the discount amount.

As an example, if you have a service with a '''Recurring Amount''' of <tt>10.00</tt> and apply a promotion code that offers a 50% discount, then the system will generate the following invoice items when the service renews:

* Invoice Item for Service Renewal: 20.00
* Promotion Code (50% Off): -10.00
* Invoice Total: 10.00

This is the recommended method to convey a discount to clients.

If you had this same service with no promotion code, then the system would generate the following invoice items upon renewal instead:

* Invoice Item for Service Renewal: 10.00
* Invoice Total: 10.00

Both invoices result in a charge of 10.00, however one shows the client that they are paying this price because of a promotion code.

If you want to provide the client with a discount, but not create a promotion code invoice item, then you could do this by either manually specifying a '''Price Override''' value when creating the order, or by modifying '''Recurring Amount'''.

==Notes==

===Limited Recurring Promotions===

The system counts the number of recurrences for a Limited Recurring promotion (which are configured using the '''Recur For x Times''' setting) by looking at the invoice line items for the service. By looking at the number of invoice line items for a service, WHMCS makes a determination for how many times it has applied the promotional discount.

After the system has used all of a promotion code's recurrences for a given service, the service will revert to the standard price automatically.

If you wish to provide an an extension of the promotion, it would be necessary to increase '''Times''' in the promotion code configuration. This will apply to all existing services using this promo code, instantly. Deleting invoices will not extend the duration of the promotional discount.

===Fixed Amount Promotions and Additional Currencies===
When defining the value for a '''Fixed Amount''' promotion, it is important to note that this value applies to the base currency. For example, if the installation's '''Base Currency''' is ''USD'', then setting the '''Value''' for a '''Fixed Amount''' promotion to 100 will provide a discount of $100.00 USD when customers use it.

If the installation has additional currencies beyond the base currency, the system will use '''Base Conversion Rate''' to determine the discount for customers using these additional currencies.

For more information, see [[Currencies]].

===Create Custom Promo===

'''Create Custom Promo''' displays next to '''Promotion''' when you manually add a new order via '''Add Order''' in the Admin Area.

Clicking this button displays a modal that allows you to specify a custom promotion code that the system will automatically create and apply to the immediate order.

Use of this feature requires that the Administrator User have both '''Use Any Promotion Code on Order''' and '''Create/Edit Promotions''' as permissions. For more about permissions, see [[Administrators_and_Permissions|Administrators and Permissions]].

=== Services With Metric Billing Enabled ===

When the system applies a recurring promotion or discount to a product or service for which metric billing enabled, '''only''' the cost of the base product will be eligible for the discount.

Any usage (metric) charge that the recurring invoice includes '''will not''' receive the promotion or discount.

AsiaPay

2023-08-09T12:18:55Z

PeterM:

== About this Module ==

[http://www.asiapay.com AsiaPay] is an online payment service and solutions provider in Asia that provides electronic payment gateway solutions. AsiaPay offers multi-currency, multi-lingual, multi-card, and multi-channel functionality together with advanced fraud detection and management solutions.

Headquartered in Hong Kong, AsiaPay supports 12 countries including Asia including: Hong Kong, China, India, Indonesia, Malaysia, Singapore, Philippines, Taiwan, Thailand and Vietnam and is rapidly expanding to new Asia Pacific markets.
{{gateways
| onetime = yes
| recurring = yes
}}

== Adding the AsiaPay Payment Gateway ==

To set up the AsiaPay payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''AsiaPay'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Optionally, update the '''Display Name''' value.
# Enter your merchant ID.
# Enter your secure hash key (see below).
# Click '''Save Changes'''.

=== Secure Hash Key ===

We recommend using the Secure Hash Key to protect against unauthorized callbacks.

<div class="docs-alert-info">As of WHMCS 6.0, configuring a Secure Hash Key is required. No callbacks will be accepted or processed without it.</div>

To setup a Secure Hash Key within your AsiaPay account, you must contact the PayDollar Service Department (service@paydollar.com) to request the Secure Hash function be enabled for your merchant account. Once enabled, you can retrieve the hash from within the Merchant Administration Interface by navigating to '''Profile > Payment Information'''.

Once you have obtained your Secure Hash, enter it into the "Secure Hash Key" field within the WHMCS Payment Gateway Configuration area for the AsiaPay module.

The instructions above are correct as of the time of writing (June 2015).

=== Return Value Link (Datafeed) ===
[[File:asiapay-datafeed.png|thumb|AsiaPay Datafeed]]
To automatically mark invoices as paid when you receive a payment via AsiaPay, enable ''Return Value Link'' inside your PayDollar account.
# Log in to your PayDollar account.
# Go to '''Profile > Payment Account Settings'''.
# Click '''Enable'''.
# Enter your WHMCS System URL, followed by <tt>modules/gateways/callback/asiapay.php</tt> (for example <tt>https://www.example.com/whmcspath/modules/gateways/callback/asiapay.php</tt>, where <tt>www.example.com/whmcspath</tt> is the path to your WHMCS installation).
# Click '''Update'''.

=== Test Mode ===

<div class="docs-alert-warning">
<span class="title">Note</span><br />
''Notes about any module-specific requirements.''
</div>

You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful to test your configuration.

== Troubleshooting ==

=== Parameter currCode Incorrect ===

Receiving this error when attempting to make a payment indicates that AsiaPay doesn't support the client's currency. This module supports the following currencies:

* USD
* HKD
* SGD
* CNY
* JPY
* TWD
* AUD
* EUR
* GBP
* CAD
* MOP
* PHP
* THB
* MYR
* IDR
* KRW

{{modules}}

File:Asiapay-datafeed.png

2023-08-09T12:14:31Z

PeterM:

File:Asiapay-datafeed..png

2023-08-09T12:13:30Z

PeterM:

DirectAdmin

2023-06-07T10:05:50Z

PeterM: /* API Token Permissions */

== About this Module ==

The DirectAdmin module allows you to add and manage DirectAdmin servers in WHMCS.
{{Provisioning_Module
| changepackage = Yes
| changepw = Yes
| usageupdates = Yes
| clientarealink = Yes
| port = 2222}}
== Adding a DirectAdmin Server ==

To set up a DirectAdmin server in WHMCS:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Servers]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Servers'''.
# Click '''Add New Server'''.
# Select ''DirectAdmin'' from the menu.
# Enter the hostname or IP address, username, password, and access hash.
#* The username and password must be for a reseller on the server.
#* You can use a [https://docs.directadmin.com/directadmin/customizing-workflow/api-all-about.html#creating-a-login-key Login Key] instead of the reseller password. For more information, see below.
# Click '''Test Connection'''.
# Enter the desired additional server details.
# Examine the displayed default port. If your server uses a different port, check '''Override with Custom Port''' and enter the correct port. For more information, see [[Server Port Overrides]].
# Click '''Save Changes'''.
# If this is the only DirectAdmin server that is currently in WHMCS, click on the name and ensure that it results in an asterisk (*) next to it. This indicates that it is the default to use when any other non-specific configuration doesn't apply.

=== Creating a DirectAdmin Product ===

You can create a product that provisions accounts on your XPanel server at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products_and_Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.

For account creation to work successfully with DirectAdmin, you must have your packages set up in your DirectAdmin control panel.

After you create your product, you must:

# Log in to your Direct Admin Server.
# Click '''Manage User Packages'''.
# Copy the package name from the list '''or''' create the package.
# In WHMCS, enter the package name in the product's '''Module Settings''' tab exactly as it appears in DirectAdmin.

=== API Token Permissions ===

With API tokens for DirectAdmin, you can restrict the actions an API token can perform. For these operations, WHMCS requires the following permissions:

<table class="table table-striped">
<tr>
<td>CMD_API_PACKAGES_RESELLER</td>
<td>CMD_API_PACKAGES_USER</td>
<td>CMD_API_ADDITIONAL_DOMAINS</td>
</tr>
<tr>
<td>CMD_API_SHOW_ALL_USERS</td>
<td>CMD_API_SHOW_USERS</td>
<td>CMD_API_SHOW_RESELLERS</td>
</tr>
<tr>
<td>CMD_API_DNS_CONTROL</td>
<td>CMD_API_DNS_MX</td>
<td>CMD_API_FTP</td>
</tr>
<tr>
<td>CMD_API_SHOW_USER_CONFIG</td>
<td>CMD_API_SYSTEM_INFO</td>
<td>CMD_API_SHOW_RESELLER_IPS</td>
</tr>
<tr>
<td>CMD_API_ACCOUNT_USER</td>
<td>CMD_SELECT_USERS</td>
<td>CMD_API_USER_PASSWD</td>
</tr>
<tr>
<td>CMD_API_MODIFY_RESELLER</td>
<td>CMD_API_MODIFY_USER</td>
<td>CMD_API_SHOW_USER_USAGE</td>
</tr>
<tr>
<td>CMD_API_RESELLER_STATS</td>
</tr>
</table>

<div class="docs-alert-info">
The [[Servers#Sync_Accounts|server sync tool]] requires the ''CMD_API_SHOW_RESELLERS'' permission. Without this permission, the system can still perform other actions.
</div>

=== WHMCS Connect ===

This module does not support [[WHMCS Connect]].

== Troubleshooting ==

===WHMCS Host Server IP is Blacklisted===

The server on which WHMCS is installed is being blocked by DirectAdmin's security measures. Usually this is caused by invalid login credentials inside WHMCS at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Servers]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Servers'''. Once the underlying cause has been resolved, remove the WHMCS server IP from /usr/local/directadmin/data/admin/ip_blacklist

===56 - Recv failure: Connection reset by peer===

Indicates the DirectAdmin server is requiring an SSL connection. Checking the secure checkbox on the server configuration page will resolve this error ('''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Servers]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Servers'''.

{{modules}}

Reports

2023-05-16T14:09:51Z

PeterM:

WHMCS includes a wide range of reports to give you in-depth reporting and analytics on the performance of your business. Many reports also include graphs and charts to help you interpret the data.

You can access this feature at '''Reports > Reports'''.

<div class="docs-alert-success">
You can customize the reports that display in this interface or create new ones. For more information, see [[Customizing Reports]].
</div>

<div class="docs-alert-warning">
By default, an admin role group can access all reports in the system if their permissions include '''View Reports'''. However, you can configure admin roles to only view selected reports at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Administrator Roles]]''' or, prior to WHMCS 8.0, '''Setup > Staff Management > Administrator Roles'''.
</div>

==Reports==

Reports display in several primary categories: '''General''', '''Billing''', '''Income''', '''Clients''', and '''Support'''.

You can export reports in CSV format or view them in a printer friendly format and print them. To do this, click on a report, click '''Tools''' in the upper-right corner, and then choose your desired option.

===Affiliates Overview===

An overview of affiliates for the current year: Visitors referred, Pending Commissions, Available to Withdraw balance, Withdrawn Amount and Total Commissions Paid.

===Aging Invoices===

A summary of outstanding invoices by the period by which they are overdue.

===Annual Income Report===

A report of the received income for the year by month, which the system converts to the base currency using rates at the time of the transaction. It includes your recorded transactions. The graph shows the previous year's income for easy comparison.

===Client Sources===

A summary of the answers clients have given to the 'How Did You Find Us?' or 'Where did you hear about us?' custom field signup question between a specified date range.

===Client Statement===

A statement of account for individual client accounts between a date range. Displays Type (add funds, transaction, invoice), date, description, credits, debits and a running balance.

===Client===

A report that allows you to generate a JSON export of data relating to a given client. We added this in version 7.5. You can choose the data points to include in the export from the following options:

* Profile Data
* Contacts
* Products/Services
* Domains
* Billable Items
* Invoices Quotes
* Transactions
* Tickets Emails
* Notes
* Activity Log

You can also access this report via the ''Export Client Data'' link on a client's '''[[Clients:Summary Tab|Summary]]''' tab.

===Clients===

A custom export of client information by applying up to five filters. CSV Export is available in the ''Tools'' menu in the top-right corner of the page.

===Clients by Country===

The total number of active services per country in map format, as well as total active unique clients per country in a table beneath the map.

===Credits Reviewer===

All the credits that you issued to clients between two dates you specify.

===Customer Retention Time===

The average lifetime of products, services, addons and domains. (This is the number of days between the registration date and the termination date.) Averages display by product and the associated billing cycle, and include both as a number of days value and a years and months value.

===Daily Performance===

A daily activity summary for a given month. Data in this report includes Completed Orders, New Invoices, Paid Invoices, Opened Tickets, Ticket Replies and Cancellation Requests.

===Direct Debit Processing===

All unpaid invoices using the [[Direct_Debit|Direct Debit]] payment method, and their owners' associated bank account, ready for manual processing.

===Disk Usage Summary===

When the '''[[Automation_Settings#Update_Usage_Statistics|Update Usage Statistics]]''' option is enabled, the system generates a report of the disk space and bandwidth usage statistics for hosting accounts on active servers. This report excludes disabled servers and hosting accounts without a matching record in WHMCS.

The cron job updates this once per day, or you can click '''Update Now''' to get current usage statistics.

===Domains===

Generate a custom export of domain name information by applying up to five filters. CSV export is available in the ''Tools'' menu in the top-right corner of the page.

===Domain Renewal Reminder Emails===

Part of a dedicated logging system for domain renewal notices. This keeps a log of all sent renewal notices, along with the date and recipients, and provides an easy way to view and export that information for ICANN compliance.

===Income by Product===

A breakdown per product or service of invoices that clients paid in a given month. This excludes overpayments and other payments to deposit funds (credit), and includes invoices paid from credit added in previous months. Because of this, it may not match the income total for the month.

===Income Forecast===

The projected income for each month of the year. Assumes all active services and domains renew on their next due date. This splits products with longer billing cycles (Quarterly, Semi-Annually, Annually, Biennially) evenly across the year. This doesn't include Addons and Billable Items.

===Invoices===

A custom export of invoice information, applying up to five filters. CSV export is available via the download link at the bottom of the page.

===Monthly Orders===

A breakdown of the number of units sold of each product per month per currency. This allows you to see your most profitable products.

===Monthly Transactions===

Provides a summary of daily payments activity for a given month per currency. The system generates this using transaction data. The '''Amount Out''' figure includes both expenditure transactions and refunds.

===New Customers===

The total number of new customers, orders, and complete orders for the current year and compares each of these to the previous year on the graph.

===PDF Batch===

A single PDF document containing multiple individual invoices (one per page). You can filter this by date range, payment methods, and status. This is useful for printing invoices for record-keeping or mailing to clients.

===Product Suspensions===

All services that are currently suspended and the reasons for their suspensions.

===Promotions Usage===

Usage statistics for each promotional code to see how often clients have used each promo code. Click the '''Drill Down''' link to see exactly which orders used the code.

===Sales Tax Liability===

Sales tax liability for the selected period (invoice sub-total before tax, tax amount, and total after tax). This does not include partial refunds that may have included sales tax refunds.

===Server Revenue Forecasts===

Income, by billing cycle, for each of your servers in the base currency. It then uses the monthly cost for each server to estimate the annual gross profit for each server.

===Services===

A custom export of service information (for example, domain, username, or server ID) by applying up to five filters. CCSV export is available in the '''Tools''' menu in the top-right corner of the page.

=== Smarty Compatibility ===

In WHMCS 8.7 and later, this report lists information about legacy Smarty tags that the system has detected in your custom theme and template files.

<div class="docs-alert-info">
Smarty 3 removed Smarty's <tt>{php}</tt>, <tt>{include_php}</tt>, and <tt>{insert}</tt> tag functionality. We deprecated these tags in WHMCS 6.0 and will remove support entirely in WHMCS 9.0. You '''must''' remove these tags from your custom themes and templates. For more information, see [[Eliminating Legacy Smarty Tags]].
</div>

The system scans for <tt>{php}</tt>, <tt>{include_php}</tt>, and <tt>{insert}</tt> tags in all of the following files within your WHMCS installation's root directory:

* All files in the following directories:
** <tt>/includes/hooks</tt>
** <tt>/modules</tt>
** <tt>/templates</tt>
** <tt>/admin/templates</tt>
* All email template files.
* All trusted directories in the installation's [[Smarty_Security_Policy#.7Binclude_php.7D_Tag_Use|custom Smarty security policy]].

Click '''Rescan Now''' to re-scan your WHMCS installation for <tt>{php}</tt>, <tt>{include_php}</tt>, and <tt>{insert}</tt> tags. Clicking '''Rescan Now''' erases the previous scan's data.

Within the report, files appear in two sections:

* '''Template Files''' lists each tag's file path, filename, and line number. The system sorts this list by the file path.
* '''Email Templates''' lists each tag's file path, filename, line number, and email template type. The system sorts this list by template type.

===Support Ticket Replies===

A breakdown of the support tickets that each admin handled for a given month. The '''Ticket''' value is the number of unique tickets that they replied to and '''Replies''' is the total number of replies across all tickets.

===Ticket Feedback Comments===

A report that displays general feedback comments from customers when the '''[[Support_Tab#Ticket_Closure_Feedback_Request|Ticket Closure Feedback]]''' option is enabled. You can filter this by date range and staff member.

===Ticket Feedback Scores===

A report that displays the ratings, on a scale of 1-10, that clients have given to individual admins when the '''[[Support_Tab#Ticket_Closure_Feedback_Request|Ticket Closure Feedback]]''' option is enabled. You can filter this by date range. Click the admin's name to see comments that clients left specifically about that member of staff.

===Ticket Ratings Reviewer===

A report that displays the score, on a scale of 1-10, that clients have given to individual support ticket replies when the '''[[Support_Tab#Support_Ticket_Rating|Support Ticket Rating]]''' option is enabled. You can filter this by date range and score.

===Ticket Tags===

An overview of assigned ticket tags for a given [[Date_Range_Picker|date range]], by ticket opening date. You can add tags to tickets via the '''Tag Cloud''' field when viewing a support ticket.

===Top 10 Clients By Income===

The 10 clients with the highest net income, according to the transactions in WHMCS. If the client does not use your default currency, the system will convert their income for ease of comparison.

===Transactions===

A custom export of transaction information by applying up to five filters. CSV export is available in the '''Tools''' menu in the top-right corner of the page.

===VAT MOSS===

This report provides the information EU businesses need to be able to complete the VATMOSS return in whatever specific format(s) your local VAT tax authority will accept.

<div class="docs-alert-info">
''' Report Name:''' VAT MOSS Settlement Data Report for WHMCS<br />
''' Version:''' 1.0<br />
''' Release Date:''' 1st April 2015<br />
''' Supported WHMCS Versions:''' 5.3+
</div>

On January 1st, 2015, new rules came into effect for handling VAT for the sale of digital products and services within the EU. The rules created a system called the Mini One-Stop Shop (MOSS) for the declaration of VAT collected on these digital supplies. For more information, see [http://blog.whmcs.com/?t=96594 New EU VAT rules from 1st January 2015].

While the submission requirements and file formats vary by MOSS country of registration, the required information is the same.

* For more information, see [http://blog.whmcs.com/?t=99502 our blog post].
* To download the report, [http://www.whmcs.com/download/702/whmcs-vat-moss-report click here].
* To install a report in WHMCS, unzip the download file and upload the <tt>vat_moss.php</tt> file to the <tt>/modules/reports/</tt> directory.

Make sure to confirm the procedure for uploading your settlement data with your tax authority. Contact your MOSS registration country if you have any further questions in relation to the MOSS return.

Namecheap

2023-04-26T14:48:04Z

PeterM: /* Activation */

== About this Module ==

The Namecheap module allows you to register and manage domains with Namecheap.
{{registrar
| register = yes
| transfer = yes
| renew = yes
| lock = yes
| dns = yes
| whois = yes
| regns = yes
| dnsmanagement = yes
| emailforwarding = yes
| domainsync = yes
}}
== Activation ==

To activate and begin using the Namecheap registrar module:

# Log in to the WHMCS Admin Area.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Domain Registrars]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Domain Registrars'''.
# Find '''Namecheap''' in the list.
# Click '''Activate'''.
# Enter your Namecheap credentials.
# Click '''Save Changes'''.
# Whitelist your server's IP address using the steps in the [https://www.namecheap.com/support/api/intro/ Namecheap documentation]. You can find this IP address in WHMCS at '''Help > [[License Information]]'''.

=== Test Mode ===

You can use test mode to simulate domain registration and management function without registering a domain or incurring charges. This can be useful to test WHMCS configurations.

== Automatic Registration ==

WHMCS allows you to set up automatic domain registration on a per-extension basis, enabling you to use different registrars for different TLDs.

To enable automatic registration, see [[Domain Pricing]].

== Automatic Domain Synchronization ==

This module supports automatic domain synchronization for syncing expiry dates and status changes for incoming transfers.

To use this, enable '''Domain Sync Enabled''' in the '''[[Domains_Tab|Domains]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. You must also make certain to configure the '''[[Crons#Domain_Sync_Cron|Domain Sync Cron]]'''.

== Troubleshooting ==

=== Registrar Error Invalid Request IP ===

Seeing this error indicates that your Server IP has not been whitelisted for API access (see above).

===Unable to obtain Nameservers for an unregistered domain===

This error occurs when the domain does not exist in your Namecheap account. This message will display when a domain transfer is in progress but will automatically disappear when the transfer is complete.

{{modules}}

Namecheap

2023-04-26T14:46:40Z

PeterM: /* Registrar Error Invalid Client IP */

== About this Module ==

The Namecheap module allows you to register and manage domains with Namecheap.
{{registrar
| register = yes
| transfer = yes
| renew = yes
| lock = yes
| dns = yes
| whois = yes
| regns = yes
| dnsmanagement = yes
| emailforwarding = yes
| domainsync = yes
}}
== Activation ==

To activate and begin using the Namecheap registrar module:

# Log in to the WHMCS Admin Area.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Domain Registrars]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Domain Registrars'''.
# Find '''Namecheap''' in the list.
# Click '''Activate'''.
# Enter your Namecheap credentials.
# Click '''Save Changes'''.
# [https://www.namecheap.com/ Open a Namecheap ticket] to request API access to your Namecheap account for your server's IP address. You can find this IP address in WHMCS at '''Help > [[License Information]]'''.

=== Test Mode ===

You can use test mode to simulate domain registration and management function without registering a domain or incurring charges. This can be useful to test WHMCS configurations.

== Automatic Registration ==

WHMCS allows you to set up automatic domain registration on a per-extension basis, enabling you to use different registrars for different TLDs.

To enable automatic registration, see [[Domain Pricing]].

== Automatic Domain Synchronization ==

This module supports automatic domain synchronization for syncing expiry dates and status changes for incoming transfers.

To use this, enable '''Domain Sync Enabled''' in the '''[[Domains_Tab|Domains]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. You must also make certain to configure the '''[[Crons#Domain_Sync_Cron|Domain Sync Cron]]'''.

== Troubleshooting ==

=== Registrar Error Invalid Request IP ===

Seeing this error indicates that your Server IP has not been whitelisted for API access (see above).

===Unable to obtain Nameservers for an unregistered domain===

This error occurs when the domain does not exist in your Namecheap account. This message will display when a domain transfer is in progress but will automatically disappear when the transfer is complete.

{{modules}}

Banned Ips

2023-04-04T14:34:48Z

PeterM: Redirected page to Banned IPs

#REDIRECT [[Banned_IPs]]

Products Management

2023-03-07T13:07:28Z

PeterM: /* Deleting a Product/Service from a Client */

WHMCS allows you to offer many different types of products and services, both with or without automation, and to create addons and other additional items to tailor those products and services to your clients' needs.

==Ordering Products and Services==

[[File:Admin-order-form.png|800px]]

To order new products and services for a client:

# Go to '''Orders > Add New Order''' or click '''Add New Order''' in the client profile.
# Begin entering the client details to select the client (if the system didn't already preselect them).
# Choose the payment method to use for the order and any resulting invoice.
# Select a promotion code to apply to the order items (if applicable).
# Choose the order status. Unless this is for adding an existing service that needs no provisioning, leave it as pending so that you can review the order after payment and ensure any provisioning was successful.
# Select one of the following options:
#*Order Confirmation — Keep this selected if you wish to send the Order Confirmation email to the client.
#*Generate Invoice — Keep this selected if you wish to generate an invoice for the items on the order. This is useful if you are placing an order for a new service on the client's behalf or you will to manually enter an existing service but still want to invoice them right away.
#*Send Email — Keep this selected if you wish to send the Invoice Created email whenever the system creates an invoice.
# Enter and select the details for each product you want to add to the order, including a domain name, billing cycle, quantity, and any pricing overrides.
#* Click '''Add New Product''' to add multiple products to the order.
#* If the billing cycle and price override fields have not changed, the system will use the pricing from the shortest configured billing cycle.
#* Use the '''Quantity''' option to order multiples of a single product that doesn't require any specific configuration on the initial order (such as a domain name and configurable options). For example, if you are selling a software license using our Licensing Addon and the customer wishes to receive 10 licenses, you could use 10 for the Quantity and the system will create 10 services on their account after order submission.
# Optionally, select and enter the appropriate details to add one or more domain names to the order.
#* Select ''None'' if this order doesn't require a domain,
#* For registration, the system will prompt you for the domain name, the number of years to register it for, any applicable addons, and finally any pricing overrides for the registration and future renewal amounts. If there isn't a price override, the system uses the regular price for that TLD.
#* For transfers, the system will prompt you for the same details, along with the EPP code (also commonly called the Transfer Authorization code) from the existing registrar for the domain. During the client area ordering process, the client supplies this, and you may need to obtain it from them first if it is applicable to the domain you are trying to transfer.
#* For '''Domain Only''' orders, you would not enter anything into the fields in the '''Product/Service''' section ('''Product/Service''', '''Domain''', '''Billing Cycle''', '''Quantity''', and '''Price Override''') and fill in the '''Domain Registration''' section.

<div class="docs-alert-info">
<span class="title">Premium Domains</span><br />
When ordering domains via the Admin Area, the system does not look up the domain's availability. WHMCS will therefore be unaware of whether it is a premium domain. For premium domains, [[Clients:Summary_Tab#Login_as_Owner|log in as the account owner]] and order them via the Client Area.
</div>

==Managing a Client's Products and Services==

You can manage a client's products and services in the '''[[Clients:Products/Services Tab|Products/Services]]''' tab in the client's profile. This tab allows you to view and modify all of a products settings. After making any changes, click '''Save Changes'''.

[[File:Module-commands.png|800px]]

If the product or service is linked to a module, the '''Module Commands''' actions display when you view that product or service for the client. This allows you to execute any of the commands available in that module.

Modules can have custom functions, but most use the same basic actions by default.

==Addons==

Product addons allow you to bill for additional items related to the main product but on independent billing cycles from the product (unlike Configurable Options, which have to bill on the same cycle).

You can create new addons or work with preconfigured addons at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Product Addons]]''' or, prior to WHMCS 8.0, '''Setup > Product Addons'''. Then, clients can order addons from the Client Area product details page or from your store.

[[File:Managing-addon.png|800px]]

After purchase, ou can manage addons for individual purchased products in the client profile.
* To view the list of addons for a product, select the parent product from the menu.
* To edit an addon, click the edit icon for that addon in the '''Addons''' list.

===Adding Addons to Clients===

[[File:New-addon-button.png|800px]]

To add a new addon for a client:

# Click '''[[Clients:Products/Services Tab|Products/Services]]''' in the client profile.
# Click '''Click here to Manage''' for '''Addons'''.
# Click '''Add New Addon'''.
# If you are adding a predefined addon, select it and leave the name, price, and billing cycle empty.
# If you are adding a custom addon that will be specific to this client, set '''Predefined Addon''' to ''None'' and enter a custom name, price, and cycle.
# To delay generation of the invoice, uncheck the generate invoice checkbox.
# Click '''Save Changes''' to complete the process.

===Promotion Codes===

You can apply promotion codes to an existing service using the menu. For more information, see [[Promotions]].

===Auto Recalculate Recurring Price on Save===

Check this option to update the recurring amount field. You can use this after changing the product, configurable options, billing cycle, or promo code to auto calculate the new recurring price. We disable this by default to ensure that the system does not overwrite any discounted rates or custom pricing.

===Overide Auto Suspension===

This option can be used to allow extra time for payment to be made for specific individuals.

You can enable or disable this option from the '''[[Clients:Products/Services Tab|Products/Services]]''' tab in the client profile.

==Invoicing Early==

There may be times where a client asks for you to invoice them for the next renewal date early.

To do this:

# Go to the '''[[Clients:Summary Tab|Summary]]''' tab for the client you want to invoice.
# Check the boxes of the products, services, addons, or domains that you want to generate an invoice for.
# Click '''Invoice Selected Items''' to create the invoice for them. You can create multiple invoices if the due dates and payment methods differ.

<div class="docs-alert-info">
* You won't be able to generate another invoice if an invoice has already been made for the next due date.
* If the '''Separate Invoices''' option is enabled in the client's profile or client group, when selecting multiple items here with the same '''Next Due Date''', a single invoice will be generated.
* The status of the service, domain or addon must be ''Pending'', ''Active'', or ''Suspended'' to generate an invoice.
</div>

==Upgrades/Downgrades==

===Admin Area===

[[File:Upgrade button.png|thumb|Upgrade/Downgrade Button]]

If you would like to change the product or service a client is assigned to and automatically charge or credit the difference for that change then you need to use the Upgrade/Downgrade process. You'll find the option for this next to the '''Products/Services''' menu in the '''[[Clients:Products/Services Tab|Products/Services]]''' tab within the client profile.

To use it:
# Go to the product that you want to change.
# Perform the correct action for your WHMCS version:
#* For WHMCS 8.0 and later, click '''More''' and choose '''Upgrade/Downgrade'''.
#* For WHMCS 7.10 and earlier, go to the product you want to change, click '''Upgrade/Downgrade'''.
# Make the new product and billing cycle selections. A preview of what the charge will be for the remainder of the current cycle will display.
# Click '''Create Order'''. The system will create an order and invoice for the change.

<html><a href="http://www.youtube.com/watch?v=wXEulukuHdo" class="docs-video-tutorial"><em>Watch the video tutorial for this feature</em><span> <img src="https://assets.whmcs.com/icons/youtube.png"> </span></a></html>

There will no immediate changes to the product after creating an upgrade order, the actual product or config option changes won't take effect until the invoice is paid. But as soon as the invoice is paid the product will be updated, the new recurring amount will be set, and with most supported control panels the upgrade is fully automated with the new package details/changes being passed over to the server module being used. Finally the upgrade email specified in the product configuration is sent to the user advising them of the new products details.

The same process can also be used for configurable options changes and billing the difference for those if the product contains them.

===Client Side===

Clients can also place orders for upgrades & downgrades themselves if you have permitted it in the product configuration. This allows clients to order upgrades/downgrades and complete them automatically without the need for any staff involvement.

For more information, including how to allow clients upgrades and how the system calculates upgrade charges, see [[Automated Upgrades and Downgrades]].

===Manual Upgrades===
There may be occasion when you wish to make an upgrade without placing an upgrade order (such as a free upgrade) or processing the upgrade before the client has paid for it.

To do this:

#Navigate to the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab.
#Change the product in the menu.
#Check '''Auto Recalculate on Save'''.
#Click '''Save Changes'''.
#Click '''Change Package''' in the '''Module Commands''' section.

==Bulk Actions==

[[File:Bulk-actions.png|thumb|Bulk Actions Tool]]

The bulk actions option in WHMCS allows you to perform changes to two or more products inside a client's profile at the same time. The changes can consist of adjustments to the status, payment method, override auto-suspend date, first payment amount, recurring amount, next due date, and billing cycle. For example, you can use this option if you want to reduce a client's price on a number of separate products to the same level, execute module commands in bulk, or if you would like to bring multiple services in line to a matching due date.

To use this feature, from the client's '''[[Clients:Summary Tab|Summary]]''' tab, check the checkboxes next to the products, services, addons, or domains you want to update. The bulk actions will display under the item lists. Additional actions can be viewed by clicking '''Show Advanced Options'''. Enter any changes you wish to make (leaving blank any fields you don't want to change) and click '''Apply''' to complete the changes.

<html><a href="http://www.youtube.com/watch?v=WLLsQML6rEU" class="docs-video-tutorial"><em>Watch the video tutorial for this feature</em><span> <img src="https://assets.whmcs.com/icons/youtube.png"> </span></a></html>

===Create Prorata Invoice===

When you change the Next Due Date of a product, service, addon, or domain, the system creates a pro-rated invoice that covers the period between the current next due date and the new one. This feature includes scenarios in which the various products have different next due dates to start with and will pro-rate each accordingly as separate line items on the invoice.

To use this, specify the new Next Due Date, check '''Create Prorata Invoice''', and then click '''Apply'''.

For example, the client could wish to pay for the following products on the 10th of the month going forward:

Product A - Next Due Date 01/01/2022 @ $30/month
Product B - Next Due Date 05/01/2022 @ $60/month

To do this, set the Next Due Date to 10/01/2022 and check the checkbox, an invoice with the following line items will be generated:

Product A (01/01/2022 - 09/01/2022) $8.00
Product B (05/01/2022 - 09/01/2022) $10.00
Total Due Today $18.00

Only once paid will the Next Due Dates for both products be updated and in future both products would be invoiced on the 10th January.

==Cancelling a Product/Service==

===Auto Terminate/Fixed Term===
You can setup products to automatically terminate after a set number of days from the date of signup. For more information refer to [[Products_and_Services#Pricing_Tab|Configuring Products/Services]].

===Clients Self Service===
[[File:Request-cancellation-form.png|800px]]

WHMCS can completely automate the process of product cancellation or wait for manual confirmation. To do this navigate to the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings''', and enable the '''Show Cancellation Link''' option.

Clients can then request cancellation of any of their products & services directly from the client area.

To fully automate cancellation and have the module terminate command run (for example to remove the hosting account from the server) check '''Cancellation Requests''' in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings''' option.

Now when the cron runs any services with a cancellation request due today will be removed from the server and the status changed in WHMCS to Cancelled. The process runs as follows:

*Client clicks ''Request Cancellation'' button on the product details page in client area
*They're prompted to provide a cancellation reason and provided 2 choices for the cancellation - either '''Instant''' (on next cron run) or at the '''End of the Current Billing Cycle'''.
*If a matching domain exists under the client's account in active status with ''Auto Renew'' enabled, the customer is given the option to disable auto renew too - thereby leaving the domain to expire.
*Any unpaid invoices for the product will be cancelled ([[Invoice_Tab#Cancellation_Request_Handling|if enabled]])
*A notification email is sent to administrators and you will be able to review the reason provided in '''Clients > Cancellation Requests'''.

====Manual Cancellation====
If the Cancellation Request setting is '''not''' enabled then at this point you must navigate to the cancellation requests page, click through to the service page and click the '''Terminate''' module command button to remove the account from the server. The cancellation request is then moved from the ''Open Requests'' page to ''Completed Requests''.

====Automated Cancellation====
If the Cancellation Request setting '''is''' enabled the cancellation request will be actioned when the daily automation cron runs on the appropriate day. For example if the ''Immediate'' option was selected it will be terminated on the next cron run, if ''End of Billing Period'' was selected it will be terminated when the cron runs on the service's Next Due Date.

====Voiding Cancellation Requests====
If a Cancellation Request has been submitted by your client and they later change their mind, it is quick and easy to void their cancellation request. Simply navigate to '''Clients > Cancellation Requests''', locate the cancellation you wish to remove, and then click the red X next to the request to remove it. This will stop the cancellation from processing automatically. You'll need to make sure to mark any invoices that were cancelled as "Unpaid" to prevent billing errors.

===Admin Scheduled Cancellations===

As an admin user, you can schedule the termination of a product at the end of the currently active period by going to the Products/Services tab, checking the '''Auto-Terminate End of Cycle''' option and optionally entering a reason/note for it. Any unpaid invoices for the product will be cancelled and will suppress any further renewal invoices from generating for this product and terminate it when the next due date is reached.
The "Cancellation Requests" setting in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings''' must also be enabled.

===Admin Immediate Cancellation===

Finally, if you want to cancel or terminate a product or service immediately then you simply need to locate the item you wish to cancel, and from the Products/Services page, click the '''Terminate''' button if the product is linked to a module or if not, manually change the dropdown status from Active to '''Cancelled'''. Once you've done this, no further invoices will generate for the item.

===Addons===
When a product or service is terminated automatically by the WHMCS System, including through the above Admin Scheduled Cancellation routine, any child addon(s) attached to the product/service will also be cancelled at the same time. Addons do not support independent scheduled cancellations of their own however.

====Termination Date====
When an addon is Cancelled or Terminated, either manually via the admin interface or automatically as part of a product termination, the Termination Date will be assigned the current date automatically.
The termination date can be edited manually at any time via the Product Addon management screens within the admin area.
<div class="docs-alert-info">A termination date can only be set/edited when the addon is in one of either Terminated or Cancelled status.</div>

==Moving a Product/Service to another Client==
[[File:Transfer product.png|thumb|Transfer Product Popup]]
#From the Products/Services details page of the product you want to move, click '''Move Product/Service to Another Client''' located at the top-right of the page
#A popup box will appear (you will need popup blockers disabled to use this)
#In the popup enter the ID of the new owner. If you don't know the client's ID the Search field can be used to search by name, company or email address. Click the client's name and the ID will be filled in.
#After selecting the desired click, click the '''Transfer''' button
#The item will then be transferred, the window will close, and the original window will refresh to show the product under its new owner.

'''N.B.''' Moving a products/service between clients within WHMCS will not have any affect on the account on the server.

===Invoices===
Invoices cannot be moved between clients, therefore when moving a product/service any invoices will remain under the old owner. Therefore it would be advisable to check the old owner's Invoices tab for any unpaid invoices for this service and cancel them. If you wish to invoice the new owner for the service, move the Next Due Date forward/back by one day and a new invoice will be generated when the cron next runs.

==Deleting a Product/Service from a Client==

#From the Products/Services details page of the product you want to delete, click '''More''' and then click '''Delete'''.
#After clicking this link, you will be asked to confirm if you are sure you want to delete the item.
#If you click No you will be returned to the page, if you click Yes, the item will be deleted and you will be taken to the next product/service under that client.

'''Note:''' Deleting a product from WHMCS will not terminate it on the server. If you wanted to remove it from the server aswell, you need to run the Terminate Module Command as explained above before deleting the record from WHMCS.

==Resending Product Welcome Email==
To re-send a product welcome email simply navigate to the client's Products/Services tab and click the "Resend Product Welcome Email" button at the bottom of the page.

Domains Management

2023-03-07T13:05:38Z

PeterM: /* Deleting a Domain from a Client */

WHMCS allows the '''automated management''' of domains with a wide selection of built in registrars.

In WHMCS, you can configure your settings and choose registrars to customize how you sell domains. After domain purchases, you can perform all of the common tasks you are likely to need when providing and supporting users with their domains.

<div class="docs-alert-warning">
<span class="title">Domain Management Features</span><br />
The exact domain management features that are available depend on the domain registrar you choose. For a list of available features, see the [[Domain_Registrars|individual registrar's documentation]].
</div>

== Domain Configuration ==

Before you can sell domains, you must configure domain registration and other important settings. You can configure the following domain-related settings:

=== System Domain Settings ===

You can configure the domain options you offer (registration, transfers, or using the client's own domain) and various payment and renewal settings in the '''[[Domains Tab|Domains]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.

=== Registrar Configuration ===

You can configure domain registrars at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Domain Registrars]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Domain Registrars'''.

You can use the [[Email]] registrar module to sell TLDs that none of the supported registrar modules allow. This lets you use WHMCS to accept the order and invoice the client while you perform the domain registration, renewals, and updates manually.

=== Domain Pricing ===

You can configure your own pricing for domain registrations at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Domain Pricing]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Domain Pricing'''.

You can also use automatic domain registration for many TLDs to ensure that WHMCS automatically submits renewal requests as soon as you receive payment.

=== Offering Free Domain Registration with Selected Packages ===

<div class="docs-alert-info">
<span class="title">Note</span><br />
In WHMCS 8.2 and higher:
* Domains cannot be renewed individually through the Client Area if they are eligible for free renewal bundled with a product or service..
* You can choose whether to send free domain renewal notices. For more information, see [[Domain Renewal Notices]].
</div>

With WHMCS, you are able to offer free domains with your packages clients purchase them with certain payment terms. For example, you might want to offer a free domain when a client purchases an annual package.

For more information, see [[Free Domains]].

== Domain Renewals ==

You can configure whether domains renew before sales, or you can enable or disable auto renewals for a specific purchased domain from within the client profile.

To disable automatic renewals for a specific domain if, for example, you do not want to generate an invoice and want the domain to expire, toggle '''Disable Auto Renew''' to '''YES''' in the '''[[Clients:Products/Services Tab|Products/Services]]''' tab of the client's profile. Clients can do this by toggling the option in the Client Area domain details page.

For specific information about domain renewals, renewal pricing, and auto-renewals in WHMCS, see [[Domain Renewals]].

=== Domain Renewal Notices ===

[[File:Domain Reminder Settings.png|thumb|Domain Reminder Settings]]

By default, the system sends at least two domain renewal notices prior to expiration and one following it.

* You can change the timing, send reminders before and after a domain's expiration date, or disable it.
* You can view information about past remimnders in the client's '''[[Clients:Emails/Notes/Logs_Tabs|Email]]''' tab or in the system logs in the [[Reports#Domain_Renewal_Reminder_Emails|Domain Renewal Reminder Emails]] report for ICANN compliance, if your module supports this.
* You can change the interval at which WHMCS sends domain renewal reminder notices at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''.
* You can customize renewal notice emails at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Email Templates]]''' or, prior to WHMCS 8.0, '''Setup > Email Templates'''.

For more information, see [[Domain Renewal Notices]].

== Customizations ==

WHMCS allows you to customize certain aspects of domain sales and management:

=== WHOIS and Domain Field Customization Retentions ===

WHMCS 7.0 introduced override capabilities to WHOIS servers and additional domain fields. These provide an easy way to maintain customisations during automatic updates. In addition, the location and format for some of these files changed.

For more information, see [[WHOIS Servers]] and [[Additional Domain Fields]].

<div class="docs-alert-warning">
WHMCS will report the results from the Whois servers. Some Whois servers may not correctly report reserved or premium domains.
</div>

=== Domain Name Length Restrictions ===

The major TLDs have length limits by default. You can specify your own for any others by adding lines like these to the WHMCS configuration.php file:

$DomainMinLengthRestrictions[".asia"] = 3;
$DomainMaxLengthRestrictions[".asia"] = 64;
$DomainMinLengthRestrictions[".ws"] = 4;
$DomainMaxLengthRestrictions[".ws"] = 63;

=== Domain Renewal Restrictions ===

Many TLDs have restrictions on renewal before and after expiration (the grace period). For example, you can typically renew a .com 40 days after the expiry date, while you can renew .uk domains between 180 days prior to expiration up to 97 days afterwards (registrar dependent).

The major TLDs have grace periods by default. You can specify your own for any others by adding lines such as these to the configuration.php file:

$DomainRenewalGracePeriods[".com"] = "40";
$DomainRenewalMinimums[".co.uk"] = "180";
$DomainRenewalGracePeriods[".co.uk"] = "97";

You can also specify multiple grace periods and minimum advance renewal restrictions in a single entry:

$DomainRenewalGracePeriods = array(".com"=>"30",".net"=>"40",".uk"=>"97");
$DomainRenewalMinimums = array(".com"=>"180",".com.au"=>"90");

There are defined default Domain Grace and Redemption Period values for over 800 of the most common TLDs and extensions. For more information, see [[Domain_Grace_and_Redemption_Grace_Periods#Domain_Grace_and_Redemption_Period_Defaults|Domain Grace and Redemption Period Defaults]].

The default Minimum Renewal Periods are:

.co.uk = 180,.org.uk = 180,.me.uk = 180,.com.au = 90,.net.au = 90,.org.au = 90

The default minimum length is three characters and the default maximum length is 63 characters for the following TLDs:

.com, net, .org, .info, biz, .mobi, .name, .asia, .tel,.in, .mn, .bz, .cc
.tv, .us, .me, .co.uk, .me.uk, .org.uk, .net.uk, .ch, .li, .de, .jp

=== Domain Pricing Page Layout ===

The '''Client Area Domain Extension Pricing''' page is at <tt>cart.php?a=add&domain=register</tt>. It is designed to provide visitors and clients an intuitive overview of your extension pricing. The layout of this client area page should aid you in promoting your best extensions.

[[File:Tld_client_spotlight_logo.png|700px]]

For more information about domain spotlights, see [[Domain Pricing Matrix]].

=== Domain Categories ===

Domain Categories are used on <tt>cart.php?a=add&domain=register</tt> to group domain TLDs into categories such as '''Popular''', '''Shopping''', or '''Real Estate''' and makes it easier for clients to navigate and find their ideal domain extension.

For more information about customising the domain categories, see [[Domain Categories]].

== Managing Client Domains ==

=== Domain Registrations ===

Some scenarios may require you to work with domain registrations as they occur:

==== Handling New Domain Registrations and Transfers ====

To perform a new domain registration or initiate a transfer, someone must first place an order for it. A customer can do that from the client area or you can create one using the admin side order process. Once you have the order, the system can process the domain registration in several ways.

* If you have '''automatic registration on payment enabled''', then you can navigate to the invoice for the domain registration order and mark it as paid, either by '''manually applying a payment''', or by '''running a capture''' from a customers selected payment method. As soon as the invoice is successfully paid, the system will submit the domain order to the domain registrar.
* If you haven't enabled automatic registration, you have the option to attempt the registration when '''accepting the pending order''' by selecting the '''Send to Registrar''' checkbox and choosing the registrar to use in the '''Registrar''' menu in the order accept options.
* If you haven't enabled automatic registration and the order is already accepted, you can navigate to the domains record within the clients profile area, and from there select a domain registrar to use in the '''Registrar''' menu. Then, save before clicking on either of the required '''Register''' or '''Transfer''' buttons in the '''Registrar Commands''' options. These buttons allow you to initiate the remote API calls manually (this is the same process as reattempting a failed registration or transfer below).

==== Handling a Failed Domain Registration ====

If an automated domain registration (or transfer initiation) attempt fails, the system will notify administrators in the following ways:

* An "WHMCS Automatic Domain Renewal Failed" email to administrator roles with the ''Account Emails'' permission.
* An entry in '''Utilities > [[To-Do List]]'''.
* And entry in '''Utilities > [[Module Queue]]'''.
**The daily '''WHMCS Cron Job Activity''' email contains a summary of pending module actions in the queue at the bottom.

Once the error has been corrected, you can have WHMCS reattempt the registration or transfer. To do this, navigate to the domain record for the domain in question. Make sure the appropriate domain registrar is selected in the '''Registrar''' menu (saving changes if you need to make an adjustment). Then, click the '''Register''' or '''Transfer''' buttons from the '''Registrar Commands''' row of buttons. The system will prompt you to confirm you want to proceed before reattempting to submit the calls to the domain registrar's API. There is no need to place a new order if it fails.

Any errors that come back from the remote systems API will display on the screen immediately when performing a manual registration attempt in this way.

For more information and common errors, see [[Domain Registrars]] or contact the registrar.

=== Domain Management for Clients ===

Clients receive full access to the management tools from the client area. If the associated registrar supports it, they can perform actions like:

* Changing or registering nameservers.
* Changing the domain's lock status.
* Changing the auto renewal setting or ordering renewals.
* Viewing or editing WHOIS information.
* Managing DNS records.
* Configuring email forwarding.
* Requesting EPP codes.

=== Domain Management for Admins ===

As an admin, you can manage individual domains from the '''[[Clients:Domains Tab|Domains]]''' tab in a client's profile.

* This displays current nameservers and lock status with the stored values from the database.
* You can use this page to perform registrar commands (for example, '''Renew''', '''Modify WHOIS''', and '''Get EPP Code''').
* You can enable or disable domain addons (for example, DNS management, ID protection and email forwarding).

==== Managing Domains In Bulk ====

The following bulk actions are available to clients beneath the Domains list in the client profile. They allow you to make the same changes to a number of domains.

To use this, select the domains to modify and select one of the following options from the menu:

*Manage Nameservers — Select '''Use default nameservers''' and WHMCS will automatically match the server to which you have assigned the hosting account for the same domain (if hosting exists), or using the system wide default for domain-only orders. Select '''Use custom nameservers''' to activate the fields to enter other nameservers.
*Auto Renewal Status — Enable or Disable Auto-Renewal of all the selected domains.
*Registrar Lock Status — Enable or Disable the registrar lock for all the selected domains.
*Edit Contact Information — Select '''Use existing account contact''' and use the menu to use the details of one of the contacts or sub-accounts under this client's account. Select '''Specify custom information below''' to enter the contact details to apply to the selected domains.
*Renew Domains — Renew the selected domains. On the next screen you will be able to choose how long to renew each domain for individually.

====Viewing/Editing Domain Nameservers====

For any domain you have assigned to a registrar module in WHMCS, viewing and editing the nameservers the domain points to is a seamless integrated process. The nameserver fields will appear as part of the domain records fields when viewing a domains details via '''[[Clients:Domains Tab|Domains]]''' tab inside a Clients Profile. The system will communicate any changes you make to those fields and submit remotely to the selected domain registrar in the background by WHMCS, and update them automatically.

====Viewing/Editing Locking Status====

Similarly, if the domain's registrar module supports domain locking and unlocking, a Registrar Lock field will appear along with the nameserver fields on the domains management page. Checking or unchecking the box and saving will submit that change to the domain registrar as well.

====Viewing/Editing WHOIS Information====

To view and make changes to the WHOIS Contact Information for a domain inside WHMCS, from the '''[[Clients:Domains Tab|Domains]]''' tab within a Clients Profile, click '''Modify Domain Contact Details''' in '''Registrar Commands'''. A screen will appear listing the current contact information, which allows you to make changes to it and submit them. The system doesn't store WHOIS Information locally in WHMCS, so it always queries it in real-time from the selected domain registrar so any updates you make will take immediate effect.

====Moving a Domain to another Client====

[[File:Transfer product.png|thumb|Transfer Domain Popup]]

To move a domain to a new client:

# When viewing the domain you want to move in the '''[[Clients:Domains Tab|Domains]]''' tab, click '''Move Domain to Another Client''' at the top-right of the page.
# In the window that appears, enter the ID of the new owner. If you don't know the client's ID, you can search by name, company, or email address. Click the client's name and the system will fill in the ID.
# Click '''Transfer'''. The system will move the domain, the window will close, and the original window will refresh to show the domain under its new owner.

This process won't change the WHOIS details on the domain. If you wish to update those, click '''Modify Contact Details''' in the '''[[Clients:Domains Tab|Domains]]''' tab.

<div class="docs-alert-warning">
You can't move invoices between clients. Because of this, when moving a domain, any invoices will remain under the old owner. We recommend that you check the old owner's Invoices tab for any unpaid invoices for this domain and cancel them. If you wish to invoice the new owner for the domain, move the Next Due Date forward or back by one day and the system will generate a new invoice when the cron next runs.
</div>

==== Deleting a Domain from a Client ====

When viewing the domain you want to delete, click '''More''' and then click '''Delete'''. After clicking this link, the system will prompt you to confirm whether you are sure you want to delete the domain.

* If you click No, you will return to the page.
* If you click Yes, the system will delete the item and you will view the next domain under that client.

Deleting a domain from WHMCS will not perform any action at the domain registrar.

===Domain Renewals===

By default, domains will invoice automatically in advance of the renewal date. Your invoice generation settings in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings''' determine how far in advance renewal invoicing occurs.

Domains will auto invoice for renewal if they are in Active status and the "Do Not Renew" option is deselected in the domains profile. Clients also have the ability to both enable and disable the Do Not Renew option via the Auto Renew settings for a domain in the client area. This can be enabled or disabled on a per domain basis.

For Auto Renew, if a domain is invoiced for renewal, and you use a merchant payment gateway, and your client has chosen to pay via that method, and they have a credit card on file, then, on the due date, the system will automatically attempt that invoice for capture.

Automatic invoices for renewal generate using the '''Recurring Amount''' value that you set for the domain at the time of purchase. This means that if you increase your domain prices, it will not affect existing clients' prices. If you would like to change existing customers pricing then that can be achieved using the [[Bulk Pricing Update Utility]].

Whenever the system marks an invoice for a domain renewal as paid, either automatically as above or manually due to an admin applying payment to it from the admin area, if you assigned the domain to a registrar module in WHMCS, then the system will send a renewal command to that domain registrar's API to process the renewal. You can control this via the setting '''Auto Renew on Payment''' in the '''[[Domains Tab|Domains]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. If '''Auto Renew on Payment''' is disabled, the system will not send a renewal command to the registrar. Instead, if '''Create To-Do List Entries''' is enabled, the system will add an entry at '''Utilities > [[To-Do List]]'''. If both '''Auto Renew on Payment''' and '''Create To-Do List Entries''' are disabled, the system will not perform any action.

Clients can also order renewals on demand at any time. This enables a client to renew a domain early, well in advance of expiry, to extend their domains at any time they wish. This is done via the shopping cart by selecting the Domain Renewals category. Domain renewals that clients order in this way use the current pricing in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Domain Pricing]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Domain Pricing''' for the renewals.

==== Subscriptions and Renewals ====

Certain payment gateways (such as PayPal® and 2Checkout) offer Subscriptions: the ability to automatically send payments of a fixed amount on a fixed schedule. Domains can have a different billing cycle from an associated service (for example, a monthly product but an annual domain) which increases the complexity for a subscription. When the gateway supports such functionality, the system creates a subscription to automatically send payment for domain renewals:

* 2Checkout Inline Mode

For other subscriptions, WHMCS will not offer clients the option to create subscriptions when paying for a domain renewal invoice:

* PayPal Subscriptions
* 2Checkout Standard Mode

==== Domain Renewal Notices ====

You can configure WHMCS to send Domain Renewal Notices before and after a domain has expired. You can use these to remind and encourage your customers to renew their expiring domains with you.

For more information on this functionality, see the [[Domain Renewal Notices]] documentation.

=== Manually Registering or Renewing a Domain ===
For some trusted customers, or your own domains, you may wish to register or renew a domain without payment. To do this:
==== Manually Registering a Domain ====
To manually register a domain:
# Navigate to the desired domain in the '''[[Clients:Domains Tab|Domains]]''' tab in the client's profile.
# Click '''Register''' in the '''Registrar Commands''' section to immediately send a registration request to the domain registrar. If the request succeeds, the expiry date will update.
==== Manually Renewing a Domain ====
To manually renew a domain:
# Navigate to the desired domain in the '''[[Clients:Domains Tab|Domains]]''' tab in the client's profile.
# Click '''Renew''' in the '''Registrar Commands''' section to immediately send a renewal request to the domain registrar. If the request succeeds, the expiry date will update.
# You should also increment the next due date if you are manually handling payment according to the steps below.
If the domain is already invoiced, and automatic renewal on payment is enabled, when that invoice is paid under normal circumstances, the system sends another domain renewal request to the registrar. If you need to stop this, perform these steps:
# Locate the invoice for the domain. To do this, click '''View Invoices''' on the domain page to see a list of invoices for just that domain.
# Copy the line item and amount for the domain from the existing line to a new invoice line item and save.
# Delete the original line item from the invoice. You are removing the actual link to the domain so no further renewal will occur.

Skrill

2023-03-07T12:57:12Z

PeterM: /* About this Module */

== About this Module ==

<div class="docs-alert-info">
For recurring payments, use the [[Skrill_1-Tap|Skrill 1-Tap]] module.
</div>

The ability to connect with millions of Skrill account holders.
* Free and quick setup
* Access to credit cards, 20+ local payment methods and support for over 80 banks
* Skrill multi-currency account, giving you access to 40+ currencies
* High-security standards and anti-fraud technology
* Seamless payment experience across mobile, tablet, and desktop
* Connect with millions of Skrill account holders

What your customers will like:
* Easy ways to pay safely online — no signup required to make payments
* Convenient and immediate payments — pay with debit and credit cards or with a bank account without any hassle
* Multiple local payment options allowing customers to pay how they want
* Internationally recognized and trusted brand
The Skrill fee structure is a competitive <tt>1.2%+0.29</tt> EUR and <tt>1%+0.29</tt> EUR for Instant bank transfer. *Fees apply to new merchants only from 1st March 2021.

Don’t have an account? [https://www.skrill.com/en/business/shopping-carts/whmcs/ Sign up] for free today!
{{gateways
| onetime = yes
| reversals = yes
}}

== Adding the Skrill Hosted Payment Solutions Payment Gateway ==

To set up the Skrill Hosted Payment Solutions payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''Skrill Hosted Payment Solutions'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Enter your Skrill credentials. You can find the '''Secret Word''' value at '''My Account > Settings > Developer Settings''' in the Skrill control panel.
# Click '''Save Changes'''.

=== Test Mode ===

This module does not support test mode.

==Troubleshooting==

===MD5 Signature Failure===

Make certain that '''Secret Word''' in the configuration at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' ('''Setup > Payment Gateways''' prior to WHMCS 8.0) matches with the word that you configured in your Skrill control panel.

{{modules}}

Transferring Domains to a New Registrar

2023-02-14T14:38:52Z

PeterM:

<div class="docs-alert-danger">
<span class="title">Important</span><br />
When you update a contact of a domain name, this may apply an Inter-Registrar Transfer Policy (IRTP) lock to the domain for 60 days. This lock will prevent you from being able to transfer the domain. We recommend consulting with your domain registrar prior to making any changes to determine whether you can bypass this.

For further information on the 60-day lock, see [https://www.icann.org/resources/pages/ownership-2013-05-03-en ICANN].
</div>

[[Domain Pricing|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'''Modify Contact Details'''.
# Change the registrant email address to your own and click '''Save Changes'''.
# Return to the client's '''Domains''' tab and click '''Get EPP Code'''.
# Note the onscreen EPP code.
# Select the new domain registrar from the '''Registrar''' menu.
# Click '''Transfer'''.

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.

<div class="docs-alert-info">
Once the transfer process is complete, click '''Modify Contact Details''' to change the registrant email address back to the client's own address.
</div>

TPP Wholesale

2023-02-09T13:13:40Z

PeterM: /* Error Codes */

== About this Module ==

The TPP Wholesale module allows you to register and manage domains with TPP Wholesale.
{{registrar
| register = yes
| transfer = yes
| renew = yes
| dns = yes
| whois = yes
| domainsync = yes
| regns = yes
| getepp = yes
| lock = yes
}}
==Activation==

To activate and begin using the TPP Wholesale registrar module:

# Log in to the WHMCS Admin Area.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Domain Registrars]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Domain Registrars'''.
# Find '''TPP Wholesale''' in the list.
# Click '''Activate'''.
# Enter your TPP Wholesale credentials. You can find these in your TPP Wholesale account at '''Reseller Settings > API Preferences'''.
# Enter the desired '''DefaultAccount''' values, or leave this blank if you want WHMCS to create client accounts on the TPP Wholesale systems and group registrations within them.
# Click '''Save Changes'''.

== Automatic Registration ==

WHMCS allows you to set up automatic domain registration on a per-extension basis, enabling you to use different registrars for different TLDs.

To enable automatic registration, see [[Domain Pricing]].

== Automatic Domain Synchronization ==

This module supports automatic domain synchronization for syncing expiry dates and status changes for incoming transfers.

To use this, enable '''Domain Sync Enabled''' in the '''[[Domains_Tab|Domains]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. You must also make certain to configure the '''[[Crons#Domain_Sync_Cron|Domain Sync Cron]]'''.

== Troubleshooting ==

=== Error Codes ===

For information about TPP Wholesale error codes, see [https://support.tppwholesale.com.au/hc/en-gb/articles/360007326597-API-WHMCS-Error-Codes the TPP Wholesale website].

{{modules}}

GoCardless

2023-02-09T13:11:07Z

PeterM: /* Troubleshooting */

== About this Module ==

<div class="docs-alert-success">
We added this payment gateway in WHMCS 7.7.
</div>

[https://gocardless.com GoCardless] is a payment gateway which allows for direct debit payments to be automated electronically.
{{gateways
| onetime = yes
| recurring = yes
| reversals = yes
}}
== Adding the GoCardless Payment Gateway ==

To set up the GoCardless payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''GoCardless'''. A GoCardless login page will appear.
# Either sign up for a new account or log in to your existing account. The system will automatically configure GoCardless for you.
# Optionally, enter a custom name for the gateway for each of your supported currencies.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
#In WHMCS 8.0 and later, enabling '''Charge Date Preference''' will allow the automation system to omit passing a <tt>charge_date</tt> value to GoCardless when the automation system triggers a payment attempt. This results in GoCardless starting the transaction as soon as possible.
# Click '''Save Changes'''.

===Change Date Prefrence===

 '''Change Date Preference''' will determine if WHMCS passes a transaction charge date to GoCardless advising when to initiate the payment.

* Disabling the option will pass through either the '''Next Due Date''' from the service or the <tt>next_possible_charge_date</tt> that GoCardless sets using the <tt>charge_date</tt> function depending on which date is later.

* If you enable the option, the system will not pass a <tt>charge_date</tt> value to GoCardless and this will result in GoCardless beginning the payment process as soon as possible.  In both scenarios, the payment attempt call to GoCardless will not occur until an invoice meets the invoice and payment capture attempt criteria that you set at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]'''.

To process the payment prior to the '''Next Due Date''' date and according to the '''Process Days Before Due''' date at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''', enable this setting. If you do not, the system may attempt the payment on or after the '''Next Due Date''' date.

=== Supported Currencies ===

GoCardless only support the following currencies:

* AUD
* CAD
* DKK
* EUR
* GBP
* NZD
* SEK
* USD <div class="docs-alert-info">We added support for USD in WHMCS 7.9.</div>

Clients who do not use one of these currencies cannot make payments using GoCardless.

=== Test Mode ===

You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful to test your configuration.

==Payment Workflow==

When the first payment is made, a mandate is set up with the client's bank. This typically takes a few days, so the invoice will change from '''Unpaid''' to '''Payment Pending''' status. At this point, you can view the mandate details and expected payment completion date by viewing the invoice. As soon as the mandate is set up and the first payment has cleared, the invoice's status will change to '''Paid''' and the service will be provisioned by WHMCS automatically.

When the renewal invoice is generated for a recurring service, a capture attempt will be made against the mandate in accordance with '''Process Days Before Due''' in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''. As it can take a few days for the payment to complete, we recommend a setting of '''3'''. This way, 3 days before the invoice '''Due Date''', the payment process will be initiated by the cron and the invoice status updated from '''Unpaid''' to '''Payment Pending'''. Payment should then complete on the invoice '''Due Date''' and the invoice will be marked '''Paid''' once the payment has cleared.

Once a mandate has been created, WHMCS can use it for processing renewal payments for any other services associated with the client as long as they are set to the GoCardless gateway as well.

When making a manual payment, customers are able to select to use a previously stored bank account or enter a new one.

Customers never leave your WHMCS installation during checkout or adding/removing a new bank account. Personal bank information is submitted directly to GoCardless and is never stored in your local WHMCS installation.

==Reversed Payments==

The Direct Debit Guarantee scheme allows the payee to file a claim for any payment taken in error. WHMCS will monitor for ''charged_back'' events from GoCardless and will automatically process these as appropriate.

To learn more, visit [[Payment Reversals]]

==Refunding Payments==

While refunds with GoCardless are not directly supported from within WHMCS, they can still be processed directly with GoCardless on a case-by-case basis through their review and approval process.

Please refer to the [https://support.gocardless.com/hc/en-ca/articles/210536269-Refunding-payments refunding payments] section of the GoCardless documentation.

== Mandates ==

<div class="docs-alert-success">
We added these features in WHMCS 7.8.
</div>

=== Reinstating Mandates ===

<div class="docs-alert-warning">
Reinstating mandates requires specific permission from GoCardless.
</div>

When a mandate has been accidentally cancelled, WHMCS can initiate steps to reinstate the mandate without having the client set it up again.

To do this:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Click the '''Manage Existing Gateways''' tab.
# Click '''Manage Cancelled Mandates'''.
# Follow the instructions in the modal that appears to reinstate a cancelled mandate.

=== Importing Existing Mandates ===

<div class="docs-alert-info">
You must disable any automatically-charged mandates that you import in order to prevent possible duplicate charges.
</div>

You can import mandates that you set up outside of WHMCS and associate them with a client.

To do this:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Click the '''Manage Existing Gateways''' tab.
# Click '''Import Existing Mandates'''.
# Follow the instructions in the modal that appears to import a active mandate to a specific client.

=== Removing Mandates ===

You can remove mandates by deleting the client's GoCardless [[Pay_Methods|pay method]].

To do this:

# Click on the pay method in the '''[[Clients:Summary_Tab|Summary]]''' tab of the client profile.
# Click '''Delete''' to [[Clients:Summary_Tab#Removing_Card_Details|remove the pay method]] and any associated mandates.

== Reconfiguring Callbacks ==

After moving WHMCS, you must perform the following steps:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
# Click '''Configure GoCardless Account Connection'''.
# Log in again using the same details.

This ensures that GoCardless stores and uses the new system URL and gateway callback file URL.

== Troubleshooting ==

===Access token not active===

You can only connect each GoCardless account to a single WHMCS at a time. If you connected the GoCardless Account to multiple WHMCS installations, only the last installation that you connected will function correctly. Previously-connected WHMCS installations will show an <tt>Access token not active</tt> error at '''Billing > [[Gateway Log]]'''.

To resolve this error, you will need to reconnect WHMCS to GoCardless by [[#Reconfiguring_Callbacks|reconfiguring callbacks]].

{{modules}}

InterWorx

2023-01-10T15:54:49Z

PeterM:

== About this Module ==

The InterWorx module allows you to add and manage InterWorx servers in WHMCS.
{{Provisioning_Module
| changepackage = Yes
| changepw = Yes
| usageupdates = Yes
| clientarealink = Yes
| port = 2443}}
== Adding an InterWorx Server ==

To set up an InterWorx server in WHMCS:

# Make certain that your server's PHP complication includes SOAP.
#* You can check this at '''Utilities > System > [[PHP Info]]'''.
#* WHMCS Technical Support cannot assist with recompiling PHP. For help, contact your system administrator or hosting provider.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Servers]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Servers'''.
# Click '''Add New Server'''.
# Select ''InterWorx'' from the menu.
# Enter the hostname or IP address.
# Enter a username and password or access hash.
# Click '''Continue'''.
# Enter the desired additional server information.
# Examine the displayed default port. If your server uses a different port, check '''Override with Custom Port''' and enter the correct port. For more information, see [[Server Port Overrides]].
# Click '''Save Changes'''.
# If this is the only InterWorx server that is currently in WHMCS, click on the name and ensure that it results in an asterisk (*) next to it. This indicates that it is the default to use when any other non-specific configuration doesn't apply.

=== Creating an InterWorx Product ===

You can create a product that provisions accounts on your InterWorx server at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products_and_Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services'''.

=== WHMCS Connect ===

This module does not support [[WHMCS Connect]].

==Troubleshooting==

===WHMCS is installed on the InterWorx server===

When as part of the account creation process InterWorx restarts apache, therefore if WHMCS is installed on the same server upon which the account is being provisioned, it will kill the WHMCS process causing a problem.

To prevent that, adjust the [https://appendix.interworx.com/current/user_guide/nodeworx-webserver-guide.html#web-server-options InterWorx Webserver Settings] so '''Force Graceful Restart''' is ''On''.

<div class="docs-alert-info">
When a user clicks '''Log in to SiteWorx''' in the Client Area, the system uses the email address on the [[Clients:Profile_Tab|client's profile]] in conjunction with the password of the [[Clients:Products/Services_Tab|client's service]]. When [[Migration_Guide#Adding_Services|manually importing services]], ensure the client's email address in WHMCS matches the email address for the account in InterWorx.
</div>

{{modules}}

Troubleshooting Sign-In using Twitter

2023-01-10T15:51:51Z

PeterM: /* We were unable to connect your account. Please contact your system administrator */

===Invalid details not saved. Please verify your details and try again===

You may receive the above error message when attempting to configure your Twitter API Credentials. It indicates that the values provided are not able to successfully authenticate with the Twitter API. This typically has three causes:

# The API credentials entered are invalid,
# The callback URLs are misconfigured,

To resolve, check the following points:

* Double-check the Consumer Key and Consumer Secret are entered correctly.
* Ensure that all three Callback URLs are specified in your Twitter App Settings (refer to [[Configuring_Sign-In_using_Twitter#Configuring_Sign-In_with_Twitter|step 4 of the configuration steps]]).

===Unable to access Sign-In Integrations page===

If you cannot access the page at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Sign-In Integrations]]''' or, prior to WHMCS 8.0, '''Setup > Sign-In Integrations''', there may be an issue in your '''Friendly URLs''' configuration.

For more information, see [https://help.whmcs.com/m/troubleshooting/l/1007451-troubleshooting-a-404-page-not-found-error-in-the-admin-area Troubleshooting a 404 Page Not Found Error in the Admin Area].

===Social login: Error We could not connect to your account===

This error can be observed on either the client login or registration pages when the page loads. It indicates an error with a custom System Theme template, usually because it was not updated for use with WHMCS 7.3.

To confirm this, change to the Six or Twenty-One themes and check whether the error continues. If not, contact the system theme template developer for further assistance.

===We were unable to connect your account. Please contact your system administrator===

This error may occur when client's attempt to register or login using Twitter. It indicates a misconfiguration in the Callback URL in your Twitter app settings.

To resolve this, [[Configuring_Sign-In_using_Twitter#Configuring_Sign-In_with_Twitter|ensure that all three Callback URLs are specified in your Twitter App Settings]].

This can also indicate that your Twitter account does not have access to Twitter API v1.1. To resolve this, request [https://developer.twitter.com/en/portal/products/elevated Elevated access with Twitter].

===Link Initiated! Please complete sign in to associate this service with your existing account. You will only have to do this once===

This is a standard response when a client clicks '''Sign In With Twitter''' on the client login page but has not yet linked their account. The client will need to log in with their client area email address and password to successfully link their Twitter account to it.

Clients can connect their accounts to Twitter at any time via this method or on the '''Security Settings''' page inside the client area when logged in.

===Link Initiated! Please complete the registration form below===

Similar to the above message, this is not an error but happens when a client clicks '''Sign Up with Twitter''' on the registration form. This will only fetch the users first and last name from Twitter as well as their email address if their settings allow it, so the user must complete the registration form to complete signing up.

Configuring Sign-In using Twitter

2023-01-10T15:50:56Z

PeterM: /* Configuring Sign-In with Twitter */

Enabling the Twitter [[Sign-In Integrations]] enables visitors and customers to register, sign in, and connect their Twitter accounts with your WHMCS installation for faster signup and automatic sign-in.

[[File:Signinintegrationslogin.png]]

==Configuring Sign-In with Twitter==

<html><a href="https://vimeo.com/231458433" class="docs-video-tutorial"><em>Watch the video tutorial for this feature.</em><span> <img src="https://assets.whmcs.com/icons/youtube.png"> </span></a></html>

<div class="docs-alert-info">
WHMCS uses Twitter API v1.1. Some Twitter accounts will require [https://developer.twitter.com/en/portal/products/elevated Elevated access] to use this version of the Twitter API.
</div>

Twitter Sign In Integration requires a Twitter app and API credentials. You can create this using your existing Twitter account. Users will only see the app name you define.

To do this:

# Log in to your Twitter account.
#: <div class="docs-alert-warning">If you change the Twitter account under which you create the app, users must re-authenticate and re-link their accounts.</div>
# Go to https://developer.twitter.com/en/portal/dashboard .
# Select '''Projects & Apps''' and then '''Overview''' from the left sidebar.
# Click '''Create App'''.
# Enter an App name. [[File:Screenshot-3.png|thumb]]
# Save the '''API Key''' and API '''Secret Key'''.
# Go to '''app settings''' and click '''Set Up''' in the '''User Authentication Settings''' section.
# Enable '''OAuth 2.0'''.
# Set '''Type of App''' to '''Web App'''.
# Enter your WHMCS Client Area URL for the callback URLs and website URL.
#* You must enter a valid callback URL.
#*We recommend adding all three possible callback URLs, replacing http://example.com/whmcs/ with your WHMCS installation URL:
#** http://example.com/whmcs/index.php
#** http://example.com/whmcs/index.php/auth/provider/twitter_oauth/callback
#** http://example.com/whmcs/auth/provider/twitter_oauth/callback
# Click '''Save'''.
# Log in to the WHMCS Admin Area.
# Navigate to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Sign-In Integrations]]''' or, prior to WHMCS 8.0, '''Setup > Sign-In Integrations'''.
# Select '''Activate''' under the Twitter heading.
# Enter your Twitter '''API Key''' in the '''ConsumerKey''' field and the '''API Secret''' into the '''ConsumerSecret''' field.
# Click '''Save & Activate'''.

WHMCS will attempt to validate and test the details you have entered. If the API key and secret are valid and successfully authenticate with the Twitter API, the values will be saved.

For troubleshooting help, see [[Troubleshooting Sign-In using Twitter]].

AWHMCS Android App

2023-01-10T15:47:39Z

PeterM: /* Setup Instructions */

<div class="docs-alert-warning">
<span class="title">Acceptable Password Characters</span><br />
Don't use the following characters in an administrator password: <tt>& " ' < ></tt> (ampersand, double quotes, single quotes, less than or greater than). Any other symbols (for example, <tt># ! £ $ % ^ * ( ) . , /</tt>) are perfectly acceptable.
</div>

aWHMCS is the Official Android App for WHMCS. For the iOS App, see [[IWHMCS iPhone App]].

The app is available for either $2.99 monthly or $29.99 per year. After you purchase a license, all of your staff can use aWHMCS in conjunction with your WHMCS installation on any of their Android devices (the same licensing scheme as with all our mobile editions).

For more information, see the [https://www.awhmcs.com aWHMCS website].

==Setup Instructions==

To set up the app:

# If you haven't already done so, order the ''Android App'' addon from our client area. It's available as an addon to a license and you can order it by logging in to our [http://www.whmcs.com/members/clientarea.php Client Area] and selecting '''View Available Addons''' from the navigation bar. When you pay, we will instantly activate the addon.
# Perform a local key update by going to '''Help > [[License Information]]''' inside your WHMCS installation and clicking '''Force License Update'''.
# Download the aWHMCS App. You can download this from the Google Play Store [https://play.google.com/store/apps/details?id=com.whmcs.awhmcs2 by searching for "aWHMCS"].
# Find and open the app on your Android device. The first time that you open the app, you will see a configuration screen to fill out your WHMCS connection details.
#* For the URL, use the URL to your WHMCS directory without a trailing slash. For example, if you installed WHMCS at <tt><nowiki>http://demo.whmcs.com/</nowiki></tt> then the URL setting would be <tt><nowiki>http://demo.whmcs.com</nowiki></tt> and the admin username and password would be the same as your login for the main admin area. Remember that your Admin account role needs to have API Access permission.
#* For the access key, open the <tt>configuration.php</tt> file for your WHMCS installation and add a line to it like the one below:<div class="source-cli">$api_access_key = "abc123";</div>Replace <tt>abc123</tt> with a random series of letters and numbers. You will also need to enter that value in the Access Key field on your phone.
# Click '''Save''' and the system will test the connection. If you entered any of the details incorrectly, you'll receive an ''Access Denied'' (username and password failure) or ''Invalid Access Key'' error message. Otherwise, the home page will appear and you will be able to start using the app.

===Security PIN===

The app offers a security Personal Identification Number (PIN) feature. When you configure a PIN, you will need to enter it when starting or returning to the aWHMCS app. If your device is lost, stolen, or friends or family use it, they won't be able to access your business data.

[[File:android_pin.png|thumb|Edit Security PIN]]

To configure the PIN:

#From the '''Home''' screen, tap the '''options''' icon.
#Tap '''Settings'''.
#Tap '''PIN code'''.
#Follow the onscreen instructions to choose your four-digit PIN and confirm it.

To change or remove the security PIN:

#From the '''Home''' screen, tap the options icon.
#Tap '''Settings'''.
#Tap '''PIN code'''.
#Enter your current PIN.
#Enter the new PIN and press '''OK''' to confirm, or tap '''Clear''' to remove the PIN protection.

==Using the App==
Don't forget to press the menu button on your handset to access extra options. Almost every screen has this ability.
If your handset does not have an options button, an icon consisting of three dots will appear in the top corner instead.

[[File:Android ss2.png]]

==Common Problems==

===Invalid IP===
An ''Invalid IP'' error indicates that you didn't add the API Access Key to the <tt>configuration.php</tt> file successfully. For help with this, see the instructions above. The <tt>$api_access_key</tt> line should go before the closing <tt>?></tt> tag.

===Access Denied===
iWHMCS uses the API to communicate with your WHMCS installation. The Administrator Roles of staff using the app will require the "API Access" permission.

To grant this permission:
#Navigate to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[Administrator Users|Admin Users]]''' or, prior to WHMCS 8.0, '''Setup > Staff Management > Administrator Roles'''.
#Edit the role to which your staff member belongs.
#Check the '''API Access''' checkbox.
#Click '''Save Changes'''.

===404 URL Not Found===
A ''Not Found'' error indicates that the system can't find the <tt>/includes/api.php</tt> file from the URL that you entered into the app's connection settings.

Make sure that the URL to your WHMCS client area is correct. It should be the same as the URL of your WHMCS Client Area. WHMCS will then navigate up the folder tree from this URL to find the <tt>api.php</tt> file.

A common mistake is to enter the Administration Area URL. The app '''requires''' the Client Area URL instead.

===aWHMCS features other than the home screen require the aWHMCS addon to be purchased===
In order to view pages other than the app home screen, you must purchase the aWHMCS addon for your main WHMCS license. If you haven't done so already, log in to our [http://www.whmcs.com/members client area] and select '''View Available Addons''' from the navigation bar.

If you have already purchased the addon, make sure you associated it with the correct license key:

# In your account in WHMCS's members area, navigate to '''Services > Licences & Services'''.
# Click '''View Details''' next to your main WHMCS license key.
# Select the '''Addons''' tab.
# Check whether the list includes the aWHMCS addon.

If you're unsure which license key you're using, navigate to '''Help > [[License Information]]''' inside your WHMCS installation's admin area.

To ensure the purchase takes immediate effect, force a remote licence check. To do this, visit '''Help > Licence Information''' and click '''Force Licence Update'''. The action of loading the page will initiate a connection to our licensing server and update your local license file.

Cross-selling and Product Recommendations In WHMCS

2022-12-06T14:44:20Z

PeterM: /* Adding Recommendations to a Product */

<div class="docs-alert-info">
<span class="title">WHMCS 8.5</span><br />
We added cross-selling and product recommendations in WHMCS 8.5.
</div>

Cross-selling allows you to display product recommendations to your customers while they shop. These products display in accordance with the products the customer has already added to the shopping cart or already purchased. You can determine the recommendations for a specific product when you configure it.

== Cross-selling Locations ==

Product recommendations display in several locations as customers order products from the Client Area:

[[File:85CartRecommendations.png|300px|Cross-selling via recommendations in the Shopping Cart]]

[[File:85CheckoutRecommendations.png|300px|Cross-selling via recommendations during Checkout and on the Confirmation page]]

You can choose which locations display recommendations when you enable and configure them (see below).

=== After Adding to the Cart ===

Clients will only see product recommendations in this step if they are associated with the product that the client added.

=== View Cart and Checkout ===

Product recommendations only display on the '''Review & Checkout''' and '''Checkout''' pages once per cart session. They will not display again until the client makes a purchase and then adds the product to a new cart session.

If you enable the '''Product Cross-sell Style''' setting, the system will group recommendations here by the associated product. If multiple products include the same recommendation, a recommended product may appear multiple times. If you disable the '''Product Cross-sell Style''' setting, no duplicates will appear.

=== Order Confirmation ===

The '''Product Cross-sell Style''' setting does not affect product recommendation display on this page. Instead, clients will see a group of recommendations for the ordered products. If you enabled '''Recommend Existing Services on Order Confirmation''', then clients will also see a group of recommendations for the products that they already own.

== Enabling and Configuring Cross-selling ==

Before customers can see product recommendations for your individual products, you must enable cross-selling for your WHMCS installation.

To do this, use the related settings at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' in the '''[[Ordering Tab|Ordering]]''' tab. You can choose where to display recommendations, how many to display, whether to recommend previously-purchased services, and whether to display details about why products are recommended.

[[File:85OrderingTabCross-selling.png|300px|Cross-selling settings in the Ordering Tab]]

For more information about these settings, see [[Ordering Tab]] and [https://help.whmcs.com/m/order_forms/l/1548191-how-to-configure-cross-selling How to Configure Cross-selling].

== Configuring Product Recommendations ==

You can configure how products appear when displaying as a recommendation in the '''Details''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]'''.

[[File:85ProductDetailsTab.png|300px|The Details Tab]]

Use the '''Product Tagline''' setting to specify a tagline for the product, and use the '''Product Short Description''' setting to specify an abbreviated description for the product.

* Currently, these only display within product recommendations.
* These settings offer [[Easy Translation|translations support]].

For more information, see [[Products and Services]] and [https://help.whmcs.com/m/order_forms/l/1548191-how-to-configure-cross-selling How to Configure Cross-selling].

== Adding Recommendations to a Product ==

You can add recommendations to individual products in the '''Cross-selling''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]'''.

[[File:85ProductCross-sellingTab.png|300px|The Cross-selling Tab]]

<div class="docs-alert-info">
A maximum of 30 items will appear in the product selection menu. Using the search feature will allow the system to display products that it did not initially list.
</div>

For more information, see [[Products and Services]] and [https://help.whmcs.com/m/order_forms/l/1548191-how-to-configure-cross-selling How to Configure Cross-selling].

Automated Upgrades and Downgrades

2022-11-18T16:56:37Z

PeterM: /* How it works */

==How it works==

In WHMCS, your clients can upgrade or downgrade their products and packages directly in the Client Area. When they place an upgrade or downgrade order, they will receive a refund for any value they haven't used of the current cycle on the existing product or service. Then, the system will charge them for the remainder of the cycle at the new product's or service's price. The next due date doesn't change.

<div align="center">
<p>'''Old Product/Service'''<br />
Price Per Day * Number of days until next due date = Amount Credited</p>
<div class="docs-alert-info">
'''Price Per Day''' in the above calculation is the '''Recurring Amount''' of the client's service divided by the number of days in the billing cycle.
</div>
<p>'''New Product/Service'''<br />
Price Per Day * Number of days until next due date = Amount Debited</p>
<div class="docs-alert-info">
'''Price Per Day''' in the above calculation is the cost of the new service divided by the number of days in the billing cycle.
</div>
<p>'''Total Payable Today = Amount Debited - Amount Credited'''</p>
</div>

===Free to Paid Products===

When a client upgrades a free product to a paid product, you must set a '''Next Due Date''' to determine when it will renew. WHMCS sets this automatically to one billing cycle from the date of upgrade.

For example, if a client upgraded from a free product to a monthly paid product on the 1st of January, the '''Next Due Date''' would become the 1st of February.

===Promotion Codes===

====Upgrade Discounts====

You can configure [[Promotions#Upgrades.2FDowngrades|promotion codes]] to apply to upgrades. This is useful for incentivizing clients to upgrade to higher-tier products. When the client places an upgrade order, they will receive the opportunity to enter a promo code. The system calculates the discount based on the total amount due. Clients receive this as a discount on the amount payable.

<div align="center">
'''Total Payable Today (from above) - Discount = Discounted Upgrade Price'''
</div>

====Lifetime Promotions====

You can configure [[Promotions|promotion codes]] to last the lifetime of a client's service, including through upgrades and downgrades. For these, the system calculates the recurring discount using the full product price after the upgrade. The recurring price is reduced accordingly and then updated on the client's service.

===Upgrade Order Handling===

If an upgrade order is not paid before the renewal invoice is generated by the daily cron task, the system cancels the upgrade order automatically and generates the renewal invoice using the current service details. To upgrade, the client must place another upgrade order.

==Clients Self Service==

To place an upgrade or downgrade order, the client must log in to the Client Area, go to '''Services > My Services''', click to view the full details for the product or service they wish to manage, and then select the desired upgrade options.

==Admin Upgrades==

Admins can also create upgrade orders from the Admin Area. The system doesn't restrict admins to the products or options in the product configuration, so admins can upgrade between any two packages. Using the upgrade process will create the prorata invoice for the difference and auto-provision it on payment.

To create an upgrade order from the Admin Area, go to the service to upgrade and click '''Upgrade/Downgrade''' in the product details tab.

==Configuration==

===Product Upgrades===

To allow clients to upgrade and downgrade their packages, you need to specify the products that can upgrade to and downgrade to each of your packages.

To do this, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Products/Services''' in the '''Upgrades''' tab of the product configuration.

To select multiple products, hold the '''Ctrl''' key while selecting the products in the list.

===Configurable Options Upgrades===

With the configurable options upgrade configuration, this allows your clients to upgrade or downgrade the configurable option selections you offer on the product. You do not need to specify any further configuration for this.

Check the checkbox and the client will see the upgrade options in the Client Area. The system calculates the upgrade price for configurable options the same way as the products above.

Custom Client Fields

2022-11-01T15:42:16Z

PeterM:

Custom Fields

2022-11-01T15:40:53Z

PeterM: /* Client Custom Fields */

Custom fields allow you to collect additional information from your clients. WHMCS allows you to set up an unlimited number of customer fields that apply to clients, individual products and services, and support departments. You can set them as either admin-only for private use or public.

For example, you might create custom questions like how a client found your site, whether they want to join the mailing list, or their VAT/Tax Number.

== Client Custom Fields ==

Custom fields for clients display in the client's profile for admins, clients, or both and can optionally display on the order form. Set these to '''Show on Order Form''' if you want the client to enter them. You can also leave them as only visible in the admin area, for private entries. The client can view and edit the field values from the client area unless you set them to admin only.

You can configure custom client fields at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Custom Client Fields|Custom Fields]]''' or, prior to WHMCS 8.0, '''Setup > Custom Client Fields'''.

<div class="docs-alert-success">
<span class="title">Searching</span><br />
* You can search for the values from custom client fields at '''Clients > View/Search Clients''' in the '''Search/Filter''' tab.
* To search a '''Checkbox''' custom field, enter "on" in the '''Custom Field Value''' field. This will display results that include the checked option.
</div>

== Product Custom Fields ==

Custom fields for products display as part of the configuration process when clients purchase a product, or you can choose to only display them in the Admin Area for purchased products. This allows you to collect further information that's specific to an individual product.

Some modules require specific fields, which you can find in the documentation for that module.

You can configure custom product fields in the '''Custom Fields''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services'''.

<div class="docs-alert-success">
<span class="title">Searching</span><br />
* You can search for the values from custom product fields at '''Clients > Products/Services''' in the '''Search/Filter''' tab for the desired product group.
* To search a '''Checkbox''' custom field, enter "on" in the '''Custom Field Value''' field. This will display results that include the checked option.
</div>

== Support Department Custom Fields ==

Custom fields for support departments display during ticket submission, or you can optionally choose to only display them in the Admin Area. They allow you to ask users for additional information when opening tickets. The system can use this for things like current usernames and passwords.

You can configure custom support department fields in the '''Custom Fields''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Support Departments]]''' or, prior to WHMCS 8.0, '''Setup > Support > Support Departments'''.

== Field Types ==

When you create a custom field, you can choose from the following field types:

* '''Text Box''' — For a text entry.
* '''Link/URL''' — A URL. The prefix http:// will automatically be prefixed to any value entered.
* '''Password''' — A value to be encrypted, will appear as a password field type in the client area.
* '''Drop Down''' — A drop-down combo box for a selection of preset options.
* '''Checkbox''' — For a yes-or-no answer.
* '''Text Area''' — For a long text entry of multiple lines.

== Validation ==

The regular expression validation rules allow you to define what value the field can accept. The system won't allow the user to proceed until it passes the validation rule. For example:

A domain name in the format "google.com":
/^([a-zA-Z0-9_-])+(\.[a-zA-Z0-9_-]+)*\.([a-zA-Z]{2,6})$/

A username between 4 and 28 characters in length, allowing only alphanumeric characters and underscores:
/^[a-z\d_]{4,28}$/i

A telephone number in the following format: (###) ###-####
/^($?[0-9]{3,3}$?|[0-9]{3,3}[-. ]?)[ ][0-9]{3,3}[-. ]?[0-9]{4,4}$/

A date in the format DD/MM/YYYY:
/^\d{1,2}\/\d{1,2}\/\d{4}$/

Numbers only (0-9, any length):
/^[0-9]+$/

See http://www.rexegg.com/regex-quickstart.html for a detailed guide.

<div class="docs-alert-warning">
You must properly escape any forward slashes in your regular expression using back slashes: \/
</div>

== Other Settings ==

Depending on the type of custom field you are creating, you can enable the following options:

=== Admin Only ===

Check '''Admin Only''' if you want to hide this in the Client Area.

=== Required Field ===

Check '''Required Field''' if you want to require a response.

=== Show on Order Form ===

Check '''Show on Order Form''' if you want to display this field on the order form in the Client Area.

=== Show on Invoice ===

Check '''Show on Invoice''' if you want this field to display on the client's invoices.

You might want to display custom fields on invoices if, for example, you have a client custom field for a Tax ID or VAT Number.

* Client custom fields will display under the name and address information on the invoice.
* Product custom fields display as part of the line item descriptions for those products.

If you enable '''Store Client Data Snapshot''' in the '''[[Invoice Tab|Invoices]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. Then, create or edit a custom field after invoice creation, the invoice won't reflect those changed values and new fields. However, future invoices will show them.

==Displaying Custom Fields in Emails==

You can add custom fields to email templates using merge fields. For more information, see [[Email_Templates#Merge_Fields|Email Templates]].

==Displaying Custom Fields on Pages==

To display custom fields on service-related pages, the merge fields take the following format, where <tt>fieldname</tt> is the name of the custom field, lowercase with no spaces:

<div class="source-cli">
{$client_custom_field_fieldnamehere}
</div>

For example, for IP address, the merge field would be:

<div class="source-cli">
{$service_custom_field_ipaddress}
</div>

For fields with Friendly Names, use the friendly name, rather than the machine name, to reference the field. For example, if the field name is:

<source lang="php">CustomerType</source>

Reference it as:

<source lang="php">
{$client_custom_field_customertype}
</source>

However, if the field name is using a friendly name, like this:

<source lang="php">
CustomerType|Type of Customer
</source>

Reference it as:

<source lang="php">
{$client_custom_field_typeofcustomer}
</source>

===Multi-line Text Areas===

For text area custom fields, you can enter data on multiple lines. By default, the system displays it in merge fields on a single line. To see the custom field data as it was entered in the field, use the following merge field:

<source lang="php">
{$client_custom_field_fieldnamehere|nl2br}
</source>
or
<source lang="php">
{$service_custom_field_ipallocation|nl2br}
</source>

==Friendly Display Names==

Sometimes, a module may require that you format a custom field value in a certain way, which may be hard for visitors to understand. WHMCS can display a friendly name to visitors on the order form, emails, and invoices, and still send the required machine code to the module.
[[File:Custom_field_friendly.png|thumb|Custom Field Friendly Names]]
To achieve this, use the format "required value|display value". For example:

*Disk Space|Your Web Quota
*10000MB|10 Gigabytes
*rbx01ssd|French Server - Solid State Drive

WorldPay

2022-10-24T10:45:38Z

PeterM: /* WorldPay FuturePay */

== About this Module ==

This module allows you to use WorldPay for one time invoices.

For information on the WorldPay module in WHMCS 8.1 and earlier, see [[WorldPay Invisible]].
{{gateways
| onetime = yes
}}

== Adding the WorldPay Payment Gateway ==

To set up the WorldPay payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''WorldPay'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Enter your WorldPay credentials.
# Click '''Save Changes'''.
# Log in to the WorldPay Merchant Administration Interface.
# Go to '''System Settings > Integration Setup : PRODUCTION'''.
# Set the '''Payment Response URL''' to <tt><nowiki><WPDISPLAY ITEM=MC_callback></nowiki></tt>.
# Check '''Payment Response enabled?''', '''Enable Recurring Payment Response''', and '''Enable the Shopper Response'''.

=== Test Mode ===

You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful to test your configuration.

==WorldPay FuturePay==

This module allows you to use WorldPay with FuturePay.
{{gateways
| type = token
| onetime = yes
| recurring = yes
| level = 3
}}
=== Adding the WorldPay FuturePay Payment Gateway ===

To set up the WorldPay FuturePay payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
# Click '''WorldPay FuturePay'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Enter your WorldPay FuturePay installation details:<br/>[[File:Wpfp2.png|800px|WorldPay FuturePay]]
## In this example, '''Installation ID''' is '''12345''' in the first row of the '''Installation''' column.
## In this example, '''Installation ID for Charges''' is '''67890''' in the second row of the '''Installation''' column.
## In this example, '''Auth Password''' is '''examplepw''' in the second row of the '''Installation''' column.
# Click '''Save Changes'''.
# Log in to the WorldPay Merchant Administration Interface.
# Go to '''System Settings > Integration Setup : PRODUCTION'''.
# Set the '''Payment Response URL''' to <tt><nowiki><WPDISPLAY ITEM=MC_callback></nowiki></tt>.
# Check '''Payment Response enabled?''', '''Enable Recurring Payment Response''', and '''Enable the Shopper Response'''.

=== FuturePay IDs ===

Once a client makes the first payment (usually at the time of ordering) the FuturePay ID is stored in the database (<tt>tblclients.gatewayid</tt>).

The Futurepay ID is displayed to staff on the invoice page and also by clicking the '''Credit Card Information''' link on the client's Summary tab.

== Auth Mode A - Capture Delay ==

The auth mode is used to turn on capture delay. A = on. You then configure the delay period in the WorldPay admin. This used to be called pre-auth mode. Capture Delay enables you to specify a delay between the authorisation of a payment and its capture. This can be helpful when determining whether you should fulfil an order since it allows you time to assess a transaction. You can cancel (void) a transaction through the WorldPay Merchant Interface before capture, thereby saving you time and money by avoiding making a refund.

When enabled, the client will not be able to tell whether you are using capture delay as it behaves exactly the same; invoices in WHMCS will still instantly be marked as paid and all automation will take place as normal.

For example; a customer makes a payment and you want to Worldpay to automatically debit this payment from the customers' card then you would turn off capture delay. If you want to delay the capture then turn it on.

===To automatically capture all payments without any delay===
Set Capture Delay in your WorldPay account to 0 (zero) - set AuthMode on your Payment Gateway page to A.

===To automatically capture all payments with a delay of 1-14 days===
Set Capture Delay in your WorldPay account to a number 1-14 - set AuthMode on your Payment Gateway page to A.

===To turn off automatic payment capture and manually capture all payments===
Set Capture Delay in your WorldPay account to OFF - set AuthMode on your Payment Gateway page to E.

== Troubleshooting ==

''N/A''

{{modules}}

File:Wpfp2.png

2022-10-24T10:37:41Z

PeterM:

Troubleshooting Sign-In using Google

2022-10-21T17:38:05Z

PeterM: /* Google Sign-In is unavailable at this time. Please try again later. Error: Not a valid origin for the client: http://example.com has not been whitelisted for client ID xxxxx */

===Invalid details not saved. Please verify your details and try again===

You may receive the above error message when attempting to configure your Google API credentials. It indicates that the credentials cannot successfully authenticate with the Google API.

If you receive this message, check your API key and secret and try again.

You should also check the Authorized Javascript Origins configuration.

To properly configure your Authorized Javascript Origin:

# Retrieve the '''WHMCS System URL''' value from '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[General Settings]]''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. For example: <div class="source-cli"><nowiki>https://demo.whmcs.com/billing/</nowiki></div>
* Remove the WHMCS installation directory from the end. For example: <div class="source-cli"><nowiki>https://demo.whmcs.com/</nowiki></div>
* Remove the trailing slash from the end. For example: <div class="source-cli"><nowiki>https://demo.whmcs.com</nowiki></div>
* Add this as an Authorised Javascript Origin.

===Google Sign-In is unavailable at this time. Please try again later===

If you receive this error message when attempting to sign in using Google, the URL in your Google app is no longer valid.

For instructions to set the URL for your Google API app, see [[Configuring Sign-In using Google]].

===Google Sign-In is unavailable at this time. Please try again later. Error: Not a valid origin for the client: http://example.com has not been whitelisted for client ID xxxxx===

Receiving this error when attempting to sign in using Google indicates that the '''Authorized Javascript Origins''' and '''Authorized redirect URIs''' in your Google app are no longer valid.

For more information, see [[Configuring Sign-In using Google]].

You will only receive this error message when you are logged in as an admin and are attempting to use the Client Area Google sign in option. To verify the cause of the error, we recommend attempting to log in while authenticated as a user.

===Remote account linking via Google has failed. Please make sure that the system clock is set properly===

In order for the authentication function to operate, your server time must be within 30 seconds of Google's server time. This error indicates the difference between the two server clocks is outside the acceptable tolerance level (timezones differences do not cause this error).

To resolve this it is necessary to sync your server clock with a NTP server to ensure it is completely accurate. You can use any NTP server of your choice, but Google do offer their own. This can be done from the server command line and typically requires root access:

<div class="source-cli"><nowiki>
ntpdate time.google.com
</nowiki></div>

Instructions for server administrators are located at https://developers.google.com/time/guides

===Verification for current settings failed===

A '''Verification for current settings failed validationResponse: {valid:false}''' error may display in the Admin Area when you attempt to activate the Google Sign-In Integration by entering valid '''Client Id''' and '''Client Secret''' credentials and clicking '''Save & Activate'''.

This error occurrs when:

* The Authorized Javascript origin or Authorised redirect URI settings are incorrect.
* The WHMCS installation is configured to use an insecure http:// connection. A secure and properly configured https:// connection is required to successfully use the Sign-In Integrations feature.

To resolve this error:

# Check the steps in [[#Invalid details not saved. Please verify your details and try again]] above.
# Ensure that an SSL certificate is properly installed on your website
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
# Adjust the '''System URL''' value so the URL begins with <tt>https://</tt>.
# Click '''Save Changes'''.
# Return to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Sign-In Integrations]]''' or, prior to WHMCS 8.0, '''Setup > Sign-In Integrations''' to complete the activation process

Google Sign-In Integrations will now be activated successfully.

Project Management

2022-10-21T17:27:53Z

PeterM: /* Projects */

== About this Addon Module ==

The '''Project Management''' addon can help you organise jobs and tasks by linking support tickets and invoices with to-do items to create projects. You can then work with these in a single interface and track internal discussions, share files, and track (and optionally bill for) time spent on individual tasks.

You can access the add-on at '''Addons > Project Management'''.

For more information, see the [https://www.whmcs.com/project-management/ WHMCS Project Management] website.

<table class="table" style="text-align:center;margin:1em 1em 1em 0;background:#F9F9F9;border:1px #AAA solid;border-collapse:collapse;width:100%;">
<tr>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Addon Name</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Latest Release</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Current Version</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Compatible With</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Included in WHMCS</th>
</tr>
<tr>
<td style="border:1px #AAA solid;padding:0.2em;">Project Management</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;color:darkgreen;">Yes</td>
</tr>
</table>

== Activating Project Management ==

Because this addon ships with WHMCS by default, you do not need to download files before you activate the addon through the [[Admin Area]].

To do this:

# If you have not already, [http://www.whmcs.com/addons/project-management/ purchase the addon].
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Addon Modules]]''' or, prior to WHMCS 8.0, '''Setup > Addon Modules'''.
# Click '''Activate''' for '''Project Management'''.
# Click '''Configure'''.
# Select the [[Administrator Roles|admin role groups]] who will have access to this addon.
# Select the [[Administrator Users|admin users]] who can configure Project Management settings within the addon.
# Click '''Save Changes'''.

== Project Management ==

The '''Project Management Overview''' lists all of your projects by default, in ascending order of due date. The list includes the title, assigned staff member, status, creation date, due date, number of days left or overdue, and the last updated date for the project.

From this page you can also review the most recent 10 [[System Logs|activity log]] entries and search for projects.

=== Projects Tab ===

This tab displays a list of projects. You can search by project title or associated ticket numbers. If there is only one match for your entered search term, the system will direct you to the project view for that project.

You can apply several filters to the list of projects:

*'''Incomplete''' — View all incomplete projects.
*'''My Incomplete''' — View your assigned incomplete projects.
*'''View All''' — View all complete and incomplete projects.
*'''Assigned To Me''' — View all projects assigned to you, including completed ones
*'''Due Within 7 Days''' — View all projects that are overdue or are due within one week.
*'''Closed''' — View only completed projects.

==== Accessing Projects via Tickets ====

When you view a ticket that is associated with a project, the project's title, due date, and status will display within the support ticket itself.

==== Accessing Projects via Clients ====

In a client's profile's '''[[Clients:Summary Tab|Summary]]''' tab, you can click '''View Projects''' under '''Other Actions''' to go to the project list at '''Addons > Project Management''' with the list already filtered by client.

=== Tasks Tab ===

This tab lists tasks for all of your projects and includes the filters that you can also use in the '''[[#Projects_Tab|Projects]]''' tab.

=== Reports Tab ===

This tab lists reports on your projects, time, and invoice amounts. You can filter them by [[Date_Range_Picker|date range]] and by admin.

== Projects ==

Everything in the Project Management addon, including tasks, tickets, invoices, attachments, and messages, requires a project.

[[File:Projectmanagementview.png|800px]]

When you access a project, all of the project's information will display in a single interface page.

At the top of the page, you can click the pencil icon to edit the project title and details.

* This includes the creation and due dates, the assigned admin, the associated client, and the project's status.
* Click '''Save''' to save your changes.
* You can search for the associated client using [[Intelligent Search]].

Use the buttons next to the project title to perform additional actions:

* Start tracking time when you work on a project ('''[[#Tracking_Time|Start Timer]]''') or stop tracking ('''End Timer''').
* Add a private staff-only note ('''Add Comment''').
* Upload a file to the project ('''Upload File''').
* Send an email using a template under the '''General Messages''' [[Email Templates|email template]] type ('''Send Email''').
* Enable or disable email notifications about the project (toggle '''Watching''' to '''On''' or '''Off''').

<div class="docs-alert-info">
The system will also send email notifications to admins who are assigned to the project or task.
</div>

The top of the page also displays basic information about the project, including the creation date, a color-coded due date, the assigned admin, the client, the status, and the date of the last update to the project.

=== Creating Your First Project ===

To create a project:

# Click '''+ New Project''' in the top right corner.
# Enter the title of the project, associated ticket number, assigned admin, associated client, the creation date, and the due date.
# Click '''Create'''.

You can also create a project directly from within a support ticket by clicking the '''Create New Project''' tab. This option only appears in tickets if the ticket is not already associated with a project.

=== Tasks ===

To add a new task to a project:

# Enter the task name in '''Add new task'''.
# Select an admin to assign to the new task.
# Set the desired due date.
# Click '''Add Task'''.

To mark a task as complete, click the checkmark icon on the left of the list.

To edit a task, click the pencil icon, make the desired changes, and click '''Save'''.

To delete a task, click the trashcan icon. You can also click the pencil icon and then click '''Delete'''.

=== Messages ===

The '''Messages''' tab allows you to add notes and other messages that all admins can see when they view the project. Clients cannot view these messages.

To add a message, enter it in the text box and click '''Post Reply'''. You can also browse for and attach files.

=== Time Tracking ===

You can start the timer to track the time spent on tasks by clicking '''Start Timer'''.

* This creates a timer entry in the '''Time Tracking''' tab. It includes the admin and the start time.
* Click '''End Timer''' to end the timer.

To assign the timer record entry to a specific task:

# Go to the '''Time Tracking''' tab.
# Click the ''Edit'' pencil icon.
# Select the relevant task from the menu.
# Optionally, adjust the admin user, start time, and end time.
# Click '''Save'''.

The system then calculates the total time for each task and for the project as a whole.

=== Tickets ===

To associate [[Support Tickets|support tickets]] with a project:

# Go to the '''Tickets''' tab.
# Click '''Associate Ticket'''.
# Optionally, search for the desired ticket number or keywords from the ticket name.
# Select tickets by checking '''Select''' for each desired ticket.
# Click '''Save'''.

A single ticket can be assigned to multiple projects, and a single project can have multiple tickets assigned to it. If a project does not have an associated client and you assign a client's ticket to that project, that client will automatically be associated with the project too.

You can create a new ticket to associate with the project by clicking '''Open New Ticket'''.

=== Billing ===

Associating invoices with projects allows you to view their status from within the project itself.

The system will automatically associate invoices using the following methods:

* Invoices with a line item including <tt>Ticket #xxxxxx</tt> followed by any associated ticket number.
* Invoices with a line item including <tt>Project #XXX</tt> followed by the ID number for the project.
* Invoices that you generated from within the project using either the '''Quick Invoice''' or '''Bill for Task Time Entries''' features.

To de-associate an invoice from a project, you must update or remove the line item description to remove the ticket or project reference.

=== Files ===

The attachments section allows you to upload files to the project without posting a message.

All attachments, both uploaded here and as attachments in messages posted on the staff messageboard, are stored under the attachments directory, in a folder structure of /projects/xxx/ where xxx is the Project ID number, so projects can be easily accessed by FTP if needed, and cleaned up.

=== Log ===

The '''Log''' tab lists a full history of each action in that project, the date and time, and the associated admin.

=== Task Templates ===

Task Templates are predefined lists of tasks to add to a project.

* You can save and import task templates from within individual projects.
* You can view a list of task templates and delete them by going to '''Settings > Task Templates''' in the top-right corner of any '''Project Management''' page.

==== Save Task List ====

To save all of the tasks in the current project as a new task template:

# Click '''Save Task List'''.
# Enter a name for the new task list.
# Click '''Save'''.

You can now replicate this task list in this or other projects.

==== Import Tasks ====

To import tasks from an existing task template:

# Click '''Import Tasks'''.
# Select the desired task template from the menu or enter text to search for a template and select it.
# Click '''Import'''.

This will import a new copy of all of the task template's tasks into your project.

== Settings ==

You can configure several '''Project Management''' settings as well as configuring permissions for related actions. To do this, click '''Settings''' in the top-right corner of any '''Project Management''' addon page.

You can configure the following settings in the '''General''' tab:

*'''Default Hourly Rate''' — Set the standard hourly rate to charge in automatic time-based billing calculations. You can override this rate on a per-case basis when generating invoices for time-based logs.
*'''Project Statuses''' — Set the available statuses for projects as a comma-separated list.
*'''Completed Statuses''' — Select the statuses to treat as completed (not incomplete or awaiting work). This defaults to '''Abandoned''' and '''Completed'''.

You can configure the following settings in the '''Client Area''' tab:

* '''Enable/Disable''' — Check to enable or uncheck to disable Client Area project access. [[File:Pma_clientarea_overview.png|thumb]]
*'''Allow Access To''' — Check the sections of the Client Area in which clients can view the status and details of their projects. To access this, add the following line to your Client Area URL: <tt>/index.php?m=project_management</tt>
[[File:Pma_clientarea_projectview.png|800px]]

You can view a list of task templates and delete them in the '''Task Templates''' tab.

You can set admin role access by checking and unchecking individual permissions in the '''Permissions''' tab.

== Homepage Widget ==

The addon also includes an [[Admin Dashboard|Admin Area Dashboard]] widget, which you can activate for your admin role group in the normal way in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[Administrator Roles|Manage Admins]]''' or, prior to WHMCS 8.0, '''Setup > Staff Management > Administrator Roles'''.

The widget allows you to see an overview of projects, including title, due date, days left, status, and recent activity.

== API ==

A range of API commands are available for the addon to facilitate project management from remote systems:

*[https://developers.whmcs.com/api-reference/addprojectmessage/ AddProjectMessage]
*[https://developers.whmcs.com/api-reference/addprojecttask/ AddProjectTask]
*[https://developers.whmcs.com/api-reference/createproject/ CreateProject]
*[https://developers.whmcs.com/api-reference/deleteprojecttask/ DeleteProjectTask]
*[https://developers.whmcs.com/api-reference/endtasktimer/ EndTaskTimer]
*[https://developers.whmcs.com/api-reference/getproject/ GetProject]
*[https://developers.whmcs.com/api-reference/getprojects/ GetProjects]
*[https://developers.whmcs.com/api-reference/starttasktimer/ StartTaskTimer]
*[https://developers.whmcs.com/api-reference/updateproject UpdateProject]
*[https://developers.whmcs.com/api-reference/updateprojecttask UpdateProjectTask]

For more information, see our [https://developers.whmcs.com/api/api-index/ API documentation].

== Upgrading ==

To apply a manual update to the '''Project Management''' addon, download the update from our website, unzip the files, and upload them to the root WHMCS directory.

The files are in the appropriate sub-directories to ensure correct upload.

== Uninstalling ==

To uninstall the module and completely remove all associated data (projects, logs, tasks, task templates, and attachments), see [[Addon_Modules_Management#Removing_An_Addon|Removing An Addon]].

== Troubleshooting ==

''N/A''

== Change Log ==

''N/A''

Domain Transfers

2022-09-14T11:11:24Z

PeterM: /* Incoming Domain Transfers */

==Overview==

* WHMCS allows your customers to transfer domains to and away from you via a varied array of registrar modules. To see if your registrar module supports Domain Transfers, you can visit the [[Domain_Registrars|Domain Registrars]] page and then review the Supported Features chart.
* A domain transfer is the process of moving a domain from one registrar to another. Once a domain transfer has been performed, the registrar the domain was transferred to will handle all information pertaining the domain and its management.
* To initiate a transfer, an order must be placed for it. Customers can place an order for a Domain Transfer via the Client Area by navigating to '''Store > Transfer Domains to Us'''. Alternatively, administrators can place an order for a Domain Transfer via the Admin Area by navigating to '''Orders > Add New Order'''.

==Incoming Domain Transfers==

[[File:Domain-transfer.png]]

* If the "Allow clients to transfer a domain to you" option is enabled in the Admin Area at Setup > General Settings > Domains tab, then your customers will see the "Transfer in a Domain" option in the Shopping Cart.
* Customers can choose to transfer in any domains with TLDs that have pricing configured in the Admin Area at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Domain Pricing]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Domain Pricing'''.

<div class="docs-alert-warning">
Domain transfers are billed and performed for the shortest configured period.
</div>

* Once the order has been completed and paid WHMCS will initiate the transfer process, and the "Domain Transfer Initiated" email notification will be sent to the customer.

You can view the authorisation code that the client submitted by visiting '''Orders > List All Orders''' and clicking on the order ID.

==Outgoing Domain Transfers==

* To initiate a transfer away from WHMCS customer's will first want to ensure that their domain name is unlocked, and they will need to get their EPP code.
* If the registrar module offers the ability, WHMCS can lock or unlock the domain name for them. Customers that want to unlock their domain name can do so via the Client Area by navigating to '''Domains > My Domains''', clicking on the domain, and then clicking on '''Registrar Lock'''.
* The EPP code is basically a password for a domain name. It is a security measure, ensuring that only the domain name owner can transfer a domain name.
* Customers can retrieve the EPP code needed to transfer their domain to a new registrar via the Client Area as well. This can be done by navigating to navigating to '''Domains > My Domains''', clicking on the domain, and then clicking on '''Get EPP Code'''.
* Administrators can retrieve the EPP code from the Admin Area if needed. This can be done by navigating to the domain's page, and then clicking on the '''Get EPP Code''' button.
* Domain names that have not yet been successfully transferred from another registrar will have the "Pending Transfer" status.

==Transfer Automation==

* With the Domain Syncronisation feature WHMCS is able to identify when a domain transfer has been completed or failed. It will ensure that the Next Due Date, Expiry Date, and Status values are updated for domains on the installation.
* Most Registrar Modules support the Domain Syncronisation functionality, however not all do. To see if your desired registrar module supports this feature you'll want to click on the module on the [[Domain_Registrars|Domain Registrars]] page and then review the Supported Features chart.
* Once the domain transfer from another registrar has completed, WHMCS will send the "Domain Transfer Completed" email notification to the customer, and the domain will be set to the "Active" status.
* If a domain transfer from another registrar fails, then WHMCS will send the "Domain Transfer Failed" email notification to the customer to let them know and advise as how to proceed.
* The following registrar modules will automatically set the domain's status to "Transferred Away" once the transfer to another registrar has been completed. This will prevent WHMCS from generating renewal invoices for the transferred domain:
**[[Enom]]
**[[ResellerClub]]
**[[HexoNet]]

2CheckOut

2022-09-08T11:06:09Z

PeterM: /* Troubleshooting */

== About this Module ==

The 2CheckOut payment gateway allows you to receive one-time and recurring payments, issue refunds, and other features.
{{gateways
| onetime = yes
| recurring = yes
| refunds = yes
| updatecc = yes
}}

== Adding the 2CheckOut Payment Gateway==

To set up the 2CheckOut payment gateway in WHMCS:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.6 and later, go to '''Addons > [[Apps and Integrations|Apps & Integrations]]''' or '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations'''.
#* For WHMCS 8.0 to 8.6, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > Payment Gateways''' and choose '''All Payment Gateways'''.
# Click '''2CheckOut'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Optionally, enter a new display name.
# Enter your vendor account number. You can find the vendor account number in your 2CheckOut account by clicking the gear icon and copying the '''Merchant Code''' value.
# Choose your desired checkout style. You can choose from the following checkout styles:
#* '''Inline Checkout''' — An iframe payment option which displays a secure payment form as an overlay when your client is making payment.
#** This allows for payment to be taken from a client without them leaving your site.
#** WHMCS recommends this checkout style when using 2CheckOut.
#* '''Standard Checkout''' — Standard Checkout will redirect a client to the 2CheckOut site to make payment before they are redirected back to your site.
# Enter your API username and password. You can create these in your 2CheckOut account:
## Go to '''Settings > Manage User Access > View Roles > Add Role''' and enable '''Manage api access'''.
## Go to '''Settings > Manage User Access > View Users > Add User''' and create a new user with the role you just created.
# For enhanced security, enter a secret word. You can create the secret word in your 2CheckOut account:
## In your 2CheckOut account, navigate to "''Integrations''".
## Copy the '''INS Secret Word''' or generate a new one. The secret word is case-sensitive and can only contain the letters a-z.
# Select a '''Recurring Billing''' setting. For more information, see the section below.
# Check '''Skip 2CO Fraud Check''' to prevent 2Checkout from performing their fraud checks on payments. If a payment in WHMCS is later determined to be fraudulent, manual action would be required to reverse the payment in WHMCS and suspend any services.
# If you use multiple currencies, set '''Convert To For Processing''' to the value of the currency your 2Checkout account. For example, if your 2Checkout account is in '''USD''', the '''Convert To For Processing''' setting must also be '''USD'''.
# Click '''Save Changes'''.

=== Recurring Billing ===

When you configure recurring billing, you can select the following options:
* ''Offer Recurring & One Time Payments'' — Provide both recurring and one-time billing options.
* ''Offer Recurring Only'' — Only provide a recurring option. This option will only appear when there is a recurring item on the invoice and the invoice is not overdue.
* '' Offer One Time Only'' — Only provide a one-time option. This option will not allow automatic recurring payments.

If you choose '''Offer One Time Only''', you must configure it in your 2CheckOut account:

# Log in to your 2CheckOut account.
# Go to the '''Integrations''' tab.
# To set the 2CheckOut callback process to automatically mark invoices paid:
## Check '''Enable INS''' and '''Enable global URL'''.
## In the '''Global URL''' field, enter <tt>https://www.example.com/whmcs/modules/gateways/callback/tco.php</tt>, where <tt>https://www.example.com/whmcs/</tt> is the URL of your WHMCS installation.
# To configure Direct Return to return clients to your WHMCS installation after payment:
## Under '''Redirect URL''' in the '''Approved URL''' field, set the URL to <tt>https://www.example.com/whmcs/modules/gateways/callback/2checkout.php</tt>, where <tt>https://www.example.com/whmcs/</tt> is the URL of your WHMCS installation.
# Click '''Update'''.

===Demo Mode===

In order to use demo mode, set the '''Demo Setting''' in your 2CheckOut account to '''Parameter''' under '''Account > Site Management'''. Then, in WHMCS, enable demo mode by checking the checkbox at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.

When you use demo mode, all callbacks from 2CheckOut will fail with the error MD5 Hash Failure if a secret word is specified. This is done intentionally by 2Checkout to protect sellers of digital goods from fraudulent purchases through their demo mode.

<div class="docs-alert-info">
In Demo Mode, valid credit card data must be submitted in order to properly perform the request. Credit cards will not be charged during this process.
</div>

==Troubleshooting==

===MD5 Hash Failure===

An MD5 Hash Failure error under '''Billing > [[Gateway Log]]''' indicates that the secret word in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways''' does not match the secret word in the 2CheckOut control panel.

To resolve this issue, ensure that the Secret Word in 2Checkout contains only letters and numbers and does ''not'' contain any invisible trailing spaces. Then, update the Secret Word value in WHMCS to match the value in your 2Checkout account

===Error Code PE101===

This error indicates that there are invalid details in the 2CheckOut module settings, such as incorrect '''Vendor Account Number''' value. Ensure that you entered the 2CheckOut correctly in the [[#Adding_the_2CheckOut_Payment_Gateway|2CheckOut gateway configuration]].

A PE101 error can also be due to an account-level issue that you must resolved with 2CheckOut:
* Account is not approved to sell.
* Account has been closed.

It is possible that 2CheckOut is not allowing the use of inline checkout. Changing to [[#Adding_the_2CheckOut_Payment_Gateway|standard checkout]] can resolve this.

===Authentication failed===

This error in the under '''Billing > [[Gateway Log]]''' indicates that either the secret word, API username, or API password are incorrect. These may be reconfigured at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.

For further information on this configuration, see above.

{{modules}}

Mailchimp

2022-08-17T14:13:15Z

PeterM:

== About this Addon Module ==

MailChimp is an email marketing and automation platform. It is free to use for up to 2,000 subscribers and allows up to 12,000 emails per month.

The WHMCS MailChimp integration uses MailChimp's ecommerce API to synchronize customer, order, and abandoned cart data with your MailChimp account. This allows you to use MailChimp to set up manual and automated campaigns.

This includes:

* Thank you messages to new customers.
* Automated followup messages on abandoned carts.
* Onboarding or drip-feed campaigns to new customers.
* Attempts to recapture lapsed customers who haven't bought anything recently.
* Rewards for your best customers (based on order count or total spent).

<table class="table" style="text-align:center;margin:1em 1em 1em 0;background:#F9F9F9;border:1px #AAA solid;border-collapse:collapse;width:100%;">
<tr>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Addon Name</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Latest Release</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Current Version</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Compatible With</th>
<th style="border:1px #AAA solid;padding:0.2em;background:#F2F2F2;text-align:center;">Included in WHMCS</th>
</tr>
<tr>
<td style="border:1px #AAA solid;padding:0.2em;">Mailchimp</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;">N/A</td>
<td style="border:1px #AAA solid;padding:0.2em;">WHMCS 7.3 and later</td>
<td style="border:1px #AAA solid;padding:0.2em;color:darkgreen;">Yes</td>
</tr>
</table>

== Activating Mailchimp ==

Because this addon ships with WHMCS by default, you only need to create a Mailchimp account and activate the addon through the Admin Area.

To do this:

# If you do not yet have a MailChimp account, you can [https://go.whmcs.com/1297/mailchimp-create-account create a free account here].
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Addon Modules]]''' or, prior to WHMCS 8.0, '''Setup > Addon Modules'''.
# Click '''Activate''' for "'MailChimp'".
# Click '''Configure'''.
# Select the admin role groups who will have access to this addon.
# Click '''Save Changes'''.
# Log in to MailChimp.
# Click the icon next to your name at the bottom left of the page.
# Select '''Account & billing'''.
# Select '''Extras > API keys'''. [[File:Mailchimp1.png|500px]]
# Click '''Create A Key'''.
# Copy the key to your clipboard. We also recommend giving the API key a label in your MailChimp account (''API Key for WHMCS'' in the example below).<br>[[File:Mailchimp2.png|500px]]
# Go to '''Addons > MailChimp'''.
# Enter the API key in WHMCS. You will see this screen the first time you access the MailChimp addon after activating it.<br>[[File:Mailchimp3.png|500px]]
# Follow the instructions to finish the setup process.

== Creating an Automated Campaign ==

To create an automated campaign:

# Log in to your [https://login.mailchimp.com/ MailChimp account].
# Navigate to '''Create > Automations'''.
# Click '''Get Started'''.
# Click '''Check out Classic Automations'''.
# Choose the '''E-Commerce''' options.<br>[[File:Mailchimp4.png|500px]]
# Select your desired email from the list of premade options or click '''Custom''' to create a new campaign using advanced mode. For example, to create an onboarding automation for new customers, you would choose these options:
## Select ''Follow up on purchases''. This option sends email after an applicable purchase according to your settings. <br/>[[File:Mailchimp5.png|500px]]
## Select ''Product category''. This option only sends email for purchases of specific types of product. <br/>[[File:Mailchimp6.png|500px]]
# Enter a name for your new automation (in this example, ''Follow up on SSL purchase'').
# Choose the mailing list that you connected with your WHMCS installation. The campaign overview will display.
# Click '''Edit''' next to the trigger to choose the applicable product category.<br/>[[File:Mailchimpedittrigger.png|500px]] <br/>This example uses ''SSL Certificates'' as the product category.<br/> [[File:Mailchimp8.png|500px]]
# Click '''Save'''.
# Design your campaign's emails. You must create at least one.<br/> [[File:Mailchimp9.png|500px]]

== New Customers ==

New customers will be added to MailChimp with their opted in or out status determined depending on their marketing e-mails selection during account creation (either via the registration page or when placing their first order). Information on configuring marketing e-mail automation can be found at [[Marketing_Emails_Automation|Marketing Emails Automation]]

==Importing Existing Customers==

The MailChimp WHMCS integration will track customer signups and ecommerce transactions immediately upon activation. To add your preexisting customers to your MailChimp mailing list, you can perform an import.

To do this:

# Go to the WHMCS Admin Area and navigate to '''Reports > More'''.
# Under '''Exports''', click '''Clients'''.
# Select the fields to export. We recommend '''First Name''', '''Last Name''', '''Company Name''', and '''Email Address'''.
# Click '''Filter''' to generate the report.
# In the top-right corner, click '''Tools''' and choose '''Export to CSV'''. This allows you to download a list of your customers in the CSV format. <br/>[[File:clients-csv-8-2.png|500px]]
# Go to MailChimp.
# Navigate to '''Lists''' and choose the list you want to import customers to.
# Navigate to '''Add contacts > Import contacts'''.
# Choose the CSV or tab-delimited text file option.
# Click '''Next'''.
# Follow the displayed instructions to upload the CSV export and complete the import process.

== Troubleshooting ==

''N/A''

== Change Log ==
''N/A''