WHMCS Documentation - User contributions [en]

Automation Settings

2024-05-17T16:56:40Z

Lawrence: /* Change Invoice Status */

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]] (credit card only) 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.

=== Enable Auto Cancellation ===
Select this to enable automatic cancellation of overdue invoices after a specific number of days. This setting automates cancellation of old, overdue invoices in the ''Unpaid'' status each time that the system cron runs.

* This setting will '''not''' cancel any overdue invoices that have partial payment or applied credit, regardless of the invoice's age.
* Invoice cancellation does '''not''' explicitly trigger additional actions. However, depending on your automation settings, additional automation may occur due to cancelled invoices.
* When the system cron cancels the applicable invoices, it will add a note to the invoice to indicate closure due to automatic cancellation.

You can view the overdue unpaid invoices that the system cancelled during the last daily task run under '''Overdue Invoice Cancellation''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Status]]'''.

<div class="docs-alert-success">We added this setting in WHMCS 8.10.</div>

=== Days Overdue ===
If you enabled '''Enable Auto Cancellation''', enter the number of days an invoice can remain overdue before the system cron job cancels it.

<div class="docs-alert-success">We added this setting in WHMCS 8.10.</div>

==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.

Transactions

2024-05-17T16:56:23Z

Lawrence: /* Searching Transactions and Handling Reversals */

WHMCS records all of your transactions and allows you to view and work with them from within the Admin Area. You can also view your merchant account balances for [[Stripe]]™, [[PayPal Basic]], [[PayPal Payments]], and [[PayPal Card Payments]].

You can view a list of transactions at '''Billing > Transactions List'''.

==Applying Payment to an Invoice==

If you receive a payment that the system hasn't automatically logged in WHMCS, you will need to manually apply it to the invoice as a transaction.

* For steps to do this, see [[Invoicing]].
* If a payment is not for any particular invoice, [[Transactions#Issuing_Credit_to_a_Client|issue credit to the client]] instead.

== Multiple Invoices ==

If you receive a payment that applies to '''multiple invoices''', click '''Add Transaction'''. This displays the same settings for applying payment to an individual invoice, but, in addition, lets you set an '''Invoice ID(s)''' value. For this setting, you can enter a comma-seperated list of all of the invoice numbers to apply this payment to. The system will apply payments in the order you enter them until the client has used the full amount. The system will automatically add any remaining amount as a credit to the user for use on future invoices.

==Adding a Manual Transaction==

If you receive payment from a client by an offline means like a check or wire transfer, you must enter transactions manually. You may also want to do this to enter external transactions, like expenditures for your servers or other services, into WHMCS.

To do this:

# Click '''Add Transaction'''.
# Choose the related client (if any), the date of the payment, and the gateway.
# Enter a description, transaction ID (if applicable), and the amount.
# If this is a payment that the client can apply to invoices later (for example, a prefunding or payment on account), select '''Add as Credit'''. This will automatically create the appropriate credit entry for the user.
# Click '''Add Transaction'''.

<div class="docs-alert-warning">
You must either enter one or more invoice IDs or select '''Add as Credit'''. If you do not do this, the system may not apply the transaction against an invoice or credit to the client's account.
</div>

==Account Prefunding/Add Funds==

Sometimes, a client may want to deposit money with you in advance (for example, if they are about to place several orders or they will be unavailable). WHMCS allows for this using '''Account Prefunding/Credit'''.

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

==Managing Credit==

Credit allows customers to have a prepaid balance on their account. This can allow customers to pay in advance and can help with overpayments.

For more information, see [[Credit/Prefunding]] and [[Adding and Working With Credit]].

==Searching Transactions and Handling Reversals==

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

If you have had a check bounce, or you've received a chargeback or dispute for a transaction you already applied, it is likely that the actions that payment should trigger, such as renewal of a product, domain registration, or renewal, have already happened and you can't reverse them. You will need to deduct the amount from your income and issue the client a new invoice to repay.

For example, you would perform the following steps for a transaction that a client paid in 2CheckOut with the transaction ID <tt>6A5245278HM</tt>:

# Click the '''Search/Filter''' tab at the top.
# Select ''2CheckOut'' as the payment gateway.
# Enter the transaction ID (<tt>6A5245278HM</tt>).
# Click submit. Any matching transactions will display. From here, we can see the transaction date, the client who made it, and the invoice they were paying.
# Click the invoice for that transaction.
# In the '''Refund''' tab, apply a "Record Only" refund to deduct the paid amount from your income and show that invoice as unpaid.
# Perform the necessary actions for each item on the invoice. For example, you might want to suspend a product from the client profile to prevent further use or contact a domain's registrar and ask whether a cancellation is possible.
# Optionally, create a new manual invoice for repayment (for example, if the dispute is a mistake or the client has contacted you) by manually creating a custom invoice. This can also apply any fees or surcharges you may have incurred for the disputed payment. '''Do not''' attempt to re-invoice the original items for repayment: that could lead to double incrementing of due dates and double renewal actions on products and services.

== Payment Gateway Balances ==

<div class="docs-alert-success">We added this feature in WHMCS 8.2 and updated the displayed details in WHMCS 8.9.</div>

You can view payment gateway balances for [[Stripe]], [[PayPal Basic]], [[PayPal Payments]], and [[PayPal Card Payments]] at '''Billing > Transactions List''' in the WHMCS Admin Area. This lets you check your financial details sooner and stay aware of trends and changes.

* The displayed balances remain in the cache for a specific amount of time and will then automatically refresh. You can also manually refresh them.
* When you click on a transaction in this list, additional details will display for that transaction.
* Balances display by default for admins with the '''Full Administrator''' role. To make this information available to other admins, assign the '''View Gateway Balances''' permission to the desired role.

<div class="docs-alert-success">If you use [[Stripe]], you can also view balances in the Admin Area Dashboard widget.</div>

<div class="docs-alert-info">For information about displaying balances in custom development, see our [https://developers.whmcs.com/payment-gateways/displaying-balances Developer Documentation].</div>

==The Gateway Logs==

If WHMCS isn't automatically handling transactions or you experience other transaction-related issues, check the related logs at '''Billing > [[Gateway Log]]'''.

Payment Reversals

2024-05-17T16:56:00Z

Lawrence: /* What are Payment Reversals? */

<div class="docs-alert-info">
<i class="fa fa-question-circle"></i>
This page describes a feature available in WHMCS 7.2 and higher.
</div>

==What are Payment Reversals?==

Payment reversals return the payment for a transaction to the buyer. This typically happens after a chargeback or having lost a [[Disputes|dispute]] with a customer (for example, a lost PayPal claim). In this situation, it is common to reverse the actions that the transaction triggered when it was originally received. The Payment Reversals feature in WHMCS automates this for you.

<div class="docs-alert-info">
* WHMCS 8.3 and higher includes support for disputes for [[Stripe]] (credit card only) and some [[PayPal]]® transactions at '''Billing > [[Disputes]]'''.
* For more information on working with disputes in WHMCS 8.2 and earlier, see [[Transactions]].
</div>

=== Supported Gateways ===

WHMCS can automatically perform payment reversals for the following supported payment gateways when they notify WHMCS of a reversal:

* [[GoCardless]]
* [[PayPal Basic]]®
* [[SlimPay]]
* [[Skrill]]

=== Reversal Actions ===

Reversals can include the following actions:

* '''Change Invoice Status''' — This action sets the invoice to the '''Collections''' status. This status can help you track invoices that have a problematic payment history (for example, invoices that have received chargebacks, [[disputes]], sold or unpaid debts, or other lost business).
* '''Change Due Dates''' — This action reverts '''Next Due Date''' increments for the products and services in an invoice. This marks the item as due or, in cases where the date is in the past, overdue, which will trigger an automated suspension until repayment.

== Enabling Automated Payment Reversals ==

To enable automated payment reversals, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''.

Make certain that you check both '''Change Invoice Status''' and '''Change Due Dates'''.

==Email Notifications==

When a payment reversal notification is received, WHMCS will send an email notification to all admins whose role group receives '''Account Emails'''. For more information, see [[Administrators_and_Permissions#Managing_Administrator_Roles|Managing Administrator Roles]].

==Making a Manual Payment Reversal==

[[File:payment_reversal.png|750px]]

A manual payment reversal can be performed when adding a refund to an invoice. To do this, check '''Reverse Payment''' when making the refund. The invoice status and next due dates will be reversed as appropriate.

<div class="docs-alert-info">
<i class="fa fa-question-circle"></i>
In WHMCS 8.3 and higher, when you perform a manual refund on an applicable transaction, you may also reverse any affiliate commissions. For more information, see [[Invoicing]] and [[Affiliates]].
</div>

==Reversal Actions for Given Items==

Reversal actions can vary depending on the products and services for an invoice:

;Hosting and Hosting Addons Invoice

: Any hosting and hosting addons that are part of the invoice for the reversed transaction will have their next due dates automatically reverted. If the payment reversal occurs as part of the cron tasks, automatic suspension, if enabled, will occur next. If the reversal is standalone, any potential suspension will run with the next scheduled automatic suspension.

;Domain Items
:You must manage domain items manually. Payment reversals do not trigger any automatic actions for domains.

;Upgrade Invoice

:WHMCS will immediately suspend any services associated with the upgrade.

;Add Funds Invoice

:WHMCS will immediately remove the credit from the client account. This could result in a negative credit balance.

;Mass Payment Invoice

:A reversed transaction will apply to each paid invoice and those invoices will go to the '''Collections''' status.

;Prorated Hosting and Hosting Addons
:The next due date of the items on the invoice will be set to the previous due date.
:If the payment reversal occurs as part of the cron tasks and automatic suspensions are enabled, suspension may occur.
:If the reversal is standalone, any potential suspend will run when the automatic suspension tasks is next scheduled.

;Custom Items

:Nothing can occur with custom invoice items. There is no relationship to use in WHMCS.

Stripe

2024-05-17T16:55:22Z

Lawrence: /* Payment Workflow */

== About this Module ==

The WHMCS Stripe payment gateway uses Stripe's tokenised storage system to submit credit card information to Stripe, which stores it remotely.

<div class="docs-alert-info">For other Stripe options, see [[Stripe ACH]] and [[Stripe SEPA]]. </div>
{{gateways
| type = token
| recurring = yes
| onetime = yes
| refunds = yes
| updatecc = yes
| deletecc = yes
| 3dsecure = yes
}}
<div class="docs-alert-warning">
The Stripe payment gateway module is not compatible with the Modern or Boxes order form templates.
</div>

== Adding the Stripe Payment Gateway ==

[[File:stripe.png|thumb|Stripe Module Settings]]

To set up the Stripe 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 '''Stripe'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Configure a display name. We recommend <tt>Credit Card</tt>.
# Go to the [https://dashboard.stripe.com/account/apikeys Stripe portal] and retrieve the publishable and secret API keys.
# Enter your Stripe API Keys. <div class="docs-alert-info"><i class="fa fa-info-circle"></i> To test Stripe, enter your [https://stripe.com/docs/keys#obtain-api-keys Stripe Test Mode API Keys].</div>
# Optionally, customize the '''Statement Descriptor Suffix''' with a maximum of 22 characters.
# In WHMCS 8.0 and later, leave the '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)''' empty. WHMCS auto-generates these. See below for more information.
# Optionally, check '''Allow Payment Request Buttons'''. See below for more information.
# Click '''Save Changes'''.
# If you use different default currencies in Stripe and WHMCS, make certain that you have also configured your Stripe account's currency with a valid exchange rate at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''. Stripe only returns transaction fees in the default currency for the Stripe account.

=== WebHook Endpoints ===

<div class="docs-alert-info">
You can use Stripe Webhooks in WHMCS v8.0 and above.
</div>

Stripe's WebHook Endpoints update WHMCS automatically with changes to your customers' cards. In WHMCS 8.0 and later, when you click '''Save Changes''', WHMCS will use the '''Stripe Publishable API Key''' and '''Stripe Secret API Key''' to generate the '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)'''.

* If you enter live API keys (<tt>sk_live</tt>), WHMCS will generate the '''Stripe WebHook Endpoint Secret'''.
* If you enter test API keys (<tt>sk_test</tt>), WHMCS will generate the '''Stripe WebHook Endpoint Secret (Test/Sandbox)'''.

WHMCS registers the WebHook Endpoints to deliver these events from Stripe:

* <tt>customer.source.updated</tt>
* <tt>payment_method.updated</tt>

To change the WebHook ID, empty '''Stripe WebHook Endpoint Secret''' and '''Stripe WebHook Endpoint Secret (Test/Sandbox)''' and click '''Save Changes'''. WHMCS will auto-generate them again with new values.

=== Payment Request Button ===

Enabling this option within the module configuration provides customers with a platform-specific payment request button (for example, Apple® Pay). For customers who don’t use Apple Pay, '''Payment Request''' supports credit cards stored in the browser, Google® Pay, and Microsoft® Pay.

==== Apple Pay ====

[[File:apple_pay_checkout.png|thumb|The Apple Pay Button on Checkout]]

When you enable this, Apple Pay allows access to payment details that users have stored in their Apple Wallet. If they're using Safari® on their iPhone® or iPad®, when they tap "Buy with Apple Pay" on your site, they'll be shown a modal payment sheet. If they're using Safari on their Mac®, and have an iOS® device in range, they'll be prompted on their device to authorize the payment, which will then be sent to the browser.

To use Apple Pay with a live Stripe API key, you must register all of the domains that will display an Apple Pay button with Apple. This includes both top-level domains (for example, <tt><nowiki>whmcs.com</nowiki></tt>) and subdomains (for example, <tt><nowiki>shop.whmcs.com</nowiki></tt>).
<div class="docs-alert-info"><i class="fa fa-info-circle"></i> An SSL certificate is '''required''' to use Apple Pay.</div>

To do this:

# Download this [https://stripe.com/files/apple-pay/apple-developer-merchantid-domain-association domain association file] and host it at <tt>/.well-known/apple-developer-merchantid-domain-association</tt> on your site. For example, if you're registering <tt><nowiki>https://example.com</nowiki></tt>, make that file available at <tt><nowiki>https://example.com/.well-known/apple-developer-merchantid-domain-association</nowiki></tt>.
# To instruct Stripe to register the domain with Apple, go to the '''[https://dashboard.stripe.com/account/apple_pay Apple Pay]''' tab in '''Account Settings''' in the Stripe Dashboard.

==== Google Pay ====

Google Pay allows customers to make payments using any credit or debit card on their Google account, including Google Play, YouTube™, Chrome™, or an Android™ device.

==== Microsoft Pay ====

Microsoft Pay allows customers to make payments using any credit or debit card on their Microsoft account.

==== Link ====
In WHMCS 8.8 and later, customers can pay using [https://stripe.com/en-ca/payments/link Link] for any Stripe transaction. Link makes payments easier by letting customers complete secure, one-click transactions using saved payment information. Stripe enables Link automatically.

For more information about disabling Link for your Stripe account, see [https://support.stripe.com/questions/how-to-turn-off-link How to Turn Off Link].

=== Test Mode ===

This module does not support test mode.

== Payment Workflow ==

[[File:stripe_checkout.png|thumb|The Stripe module on Checkout]]

The Stripe module supports automated recurring and on-demand billing.

Customers can choose between previously-stored cards or entering new ones during payment, and they can update their credit cards at any time in the Client Area. Admins can also update credit card information in the WHMCS Admin Area.

During checkout, clients never leave WHMCS. Personal card information goes directly to Stripe and is never stored within WHMCS. The Stripe API handles all refunds and obtains transaction information.

* In WHMCS 7.8 and later, WHMCS uses the Stripe Elements implementation method. When performing checkout, if customer authorization is required, the system will prompt the user automatically to approve the payment. This process is also commonly referred to as 3D Secure. Use of 3D Secure depends on the card type and issuer.
* In WHMCS 8.8 and later, Stripe module transactions [https://support.stripe.com/questions/guide-for-indian-government-regulations-on-network-tokenization meet all Reserve Bank of India requirements].

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

===Recurring Payments===

Automated recurring payments use stored tokens. If a client card requires SCA, the system will deny the payment attempt and the client must log in to WHMCS manually to process the payment.

== Payment Gateway Balances ==

In WHMCS 8.2 and later, you can view payment gateway balances directly within the WHMCS Admin Area, with native support for Stripe balances.

At '''Billing > [[Transactions]]''', you can view balances in the transaction list and in the transaction details for individual transactions. For more information, see [[Payment Gateway Balances and Transactions]].

This requires you to enable '''View Gateway Balances''' for the desired administrator role at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Administrator Roles]]'''.

<div class="docs-alert-warning">
In the Admin Area [[Admin_Dashboard|Dashboard]], you can view your Stripe balances through the '''Stripe Balance''' widget. However, this widget does not use the <tt>WHMCS\Module\Gateway\Balance</tt> and <tt>WHMCS\Module\Gateway\BalanceCollection</tt> classes to display balances. For more information, see [[Stripe Balance Widget]].
</div>

== Migrating to Stripe ==

The Stripe payment gateway module supports migrating locally-stored credit card details to Stripe's tokenized storage. This is useful when you transition from another non-tokenized merchant gateway provider to Stripe.

For an existing client with a locally-stored credit card, the first time that the system attempts to capture payment for an invoice using Stripe, the system will submit the credit card details to Stripe and create and store a token. Then, the system will remove the local copy of the card details.

To migrate to Stripe and ensure all future credit card processing uses it:

# Go to the appropriate location for your version of WHMCS:
#* For WHMCS 8.6 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[Apps and Integrations|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'''.
# Activate the Stripe module.
# Click '''Deactivate''' for your previous merchant gateway provider.
# Select Stripe as the replacement gateway to switch users of the previous gateway module to.
# Click '''OK'''.

<div class="docs-alert-warning">
<span class="title">PCI DSS Compliance</span><br />
After migrating to Stripe, you may receive an email from Stripe requesting that you complete the [https://listings.pcisecuritystandards.org/documents/SAQ_D_v3_Merchant.pdf Self Assessment Questionnaire D] (SAQ D) form.

This is because the system is attempting to send raw card data that your previous merchant gateway stored to Stripe's API. You can only do this when your Stripe account has been flagged as [https://stripe.com/guides/pci-compliance PCI compliant].

To gain full access to Stripe's API, complete the SAQ D form to certify that you are PCI compliant and send it to Stripe. Stripe can then enable use of raw card data with their API.

For more information, [https://support.stripe.com/ contact Stripe support].
</div>

=== Migrating from a 3rd Party Stripe Module ===

The WHMCS Stripe module uses the Stripe <tt>cus_</tt> reference to capture payments (for example, <tt>cus_9MvIb7UlgJfJTn</tt>). The WHMCS Stripe module can replace any third-party module that uses this.

To check whether your current Stripe module uses the <tt>cus_</tt> reference, navigate to a client that you know has an active Stripe token and click on one of the pay methods in the '''Summary''' tab of the client's profile. Verify that the listed token includes the <tt>cus_</tt> prefix.

To start using the WHMCS Stripe module:

# Note the internal name of the previous Stripe module, which you can find by looking in the gateway column in the <tt>tblpaymentgateways</tt> database table.
# Activate our official Stripe module.
# Deactivate the previous Stripe module.
# Check one of the Stripe pay methods on a client. If the token contains <tt>cus{_}</tt>, you can use it with our module but it will require a manual database edit first. To allow that, run the following SQL query using phpMyAdmin or another tool, replacing "example" with the name of the previous module: <source lang="sql">UPDATE tblpaymethods SET gateway_name = 'stripe' WHERE gateway_name = 'example'; </source>
# Remove any third-party files and template customisations for the previous Stripe module.

==Troubleshooting==

===Remote Transaction Failure. Please Contact Support===

This issue has multiple causes. This may also display as '''Error'''.

To resolve this issue:

# Go to '''Billing > Gateway Log'''.
# Check the '''Result''' and '''Debug Data''' columns for error messages or codes from the time of the payment attempt.
# Perform the appropriate steps in Stripe's [https://stripe.com/docs/error-codes Error Codes] and [https://stripe.com/docs/declines/codes Declines Codes] documentation.

See below for other common causes of this error:

====Payment Blocked By Stripe====

This indicates that a rule in your Stripe account may be blocking payment.

To resolve this:

# Log in to your [https://dashboard.stripe.com/ Stripe Dashboard].
# Go to '''Developers > Logs'''.
# Find the log entries from the time at which the payment was attempted. The details of the log will show whether the payment was blocked (for example, with a '''The zip code you supplied failed validation''' error).
# Adjust the rules in your Stripe account for the error. For help, contact [https://support.stripe.com/ Stripe support].

====Customisations====

This issue may also present itself as '''"No Stripe Details Found for Update"''' in the '''Gateway Log'''.

This issue can occur due to interference from a third-party Stripe module. Using the official Stripe module requires the full uninstallation and removal of any custom or third-party Stripe integrations. This includes removal of all files and template modifications.

For example, these issues may trigger this error:

* A hook file in <tt>/includes/hooks/stripe.php</tt>. Remove this file when switching to the WHMCS Stripe module.
* Template customisations in your active order form template files.
* The payment method is set to a module other than Stripe. In this case, perform one of the following actions:
** Change the client's '''Payment Method''' setting in the client's '''Profile''' tab to the Stripe module.
** Make Stripe the system default payment gateway 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'''.

====Out Of Date Template Files====

The error indicates that you have out-of-date template files. Make certain that your client theme and order form templates are fully compatible with your version of WHMCS. The [[Release Notes]] for each version of WHMCS provide links to template changes.

====Network Analyser Tool====

Another method to diagnose this error is to use your browser's network analyser tool. Please see the section '''Another Error Type''' in [https://help.whmcs.com/m/troubleshooting/l/1312423-an-error-occurred-while-communicating-with-the-server-please-try-again this help article]. Whilst the article is for another issue, it describes how to use your browser's network analyser tool to help identify underlying errors.

===No Stripe Customer Details Found===
The system logs this error in the debug data section of '''Billing > [[Gateway Log]]'''. It indicates that the client does not have a payment method in WHMCS. You can confirm this in the '''[[Pay Methods]]''' section of the client's '''[[Clients:Summary Tab|Summary]]''' tab.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click '''Pay Now''' to make a payment via Stripe. This will create a payment method to use for future automatic payments.

==="You must provide a value for 'cvc'===

If you see at '''Billing > [[Gateway Log]]''' for a failed payment attempt by an admin or the cron job, this indicates that the customer is in an European country or has a European billing address. Stripe's API requires that they make at least one manual payment to get added to their system.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click '''Pay Now''' to make a payment via Stripe.

For more information, see [https://stripe.com/docs/api?lang=python#create_card_token Stripe's documentation] (click '''show child parameters''').

When you do this, the system displays the following data:

cvc
usually required
Card security code. Highly recommended to always include this value, but it's only required for accounts based in European countries.

After the customer makes a manual payment, the system adds them to Stripe and any future attempts (automatic or manual) will work normally.

===Network error [errno 35]: Unsupported SSL protocol version===
This error indicates a server configuration issue. The server is attempting a secure connection to Stripe using an outdated SSL protocol. Most providers now require connections via TLS for security purposes. For more information, see [https://stripe.com/docs/security#tls Stripe TLS Documentation].

To resolve this issue, work with your system administrator or hosting provider to ensure that remote cURL connections use TLS by default. You may also need to update your OpenSSL version.

===You passed an empty string for 'statement_descriptor'===
This indicates an empty '''Statement Descriptor''' field in the payment gateway configuration. Make certain that you set your entire [[#Adding_the_Stripe_Payment_Gateway|gateway configuration]].

===Bad Request===
This error may appear in the Client Area when a client attempts to pay for an invoice or order using an existing stored payment method. It indicates that the customer or the token in WHMCS do not exist in Stripe. To ensure that the pay method is correctly stored in Stripe, delete the stored payment method from the Admin Area via the client's profile's '''[[Clients:Summary Tab|Summary]]''' tab (which may display a more-informative error to administrators). Then, add the payment method again.

Customised or outdated system themes or order form templates can also cause this error. To troubleshoot this:

# Go to the '''[[General Tab|General]]''' 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 ''Six'' or ''Twenty-One'' for '''System Theme'''.
# Go to the '''[[Ordering Tab|Ordering]]''' tab.
# Select a '''[[Standard_Order_Form_Templates|Default Order Form Template]]'''.
# Click '''Save Changes'''.
# Return to the Client Area and refresh the page.

<div class="docs-alert-warning">
<span class="title">Client Area System Themes</span><br />
We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future version.
</div>

===An unexpected error - No Stripe Payment Method found from token===
This error indicates that the system could not transmit some of the required data to Stripe. This is usually due to outdated order form templates. Check this issue using the Twenty-One or Six system theme and the Standard Cart order form template.

<div class="docs-alert-warning">
<span class="title">Client Area System Themes</span><br />
We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future version.
</div>

This can also be caused by a JavaScript error from custom code (for example, template changes, hooks, or addons) preventing the standard Stripe JavaScript from running correctly. Your browser console will show whether a JavaScript error is occurring.
* If one is, the custom JavaScript will need to be corrected.
* If the JavaScript error is coming from a third-party customisation, contact the developer for assistance.

If the issue persists, contact our [https://www.whmcs.com/submit-a-ticket/ support team].

===Error Updating Remote Pay Method: Remote Storage Failed===
You can find information about this error at '''Billing > [[Gateway Log]]'''.

===Stripe India Accounts===
India-based Stripe accounts require the following additional conditions for a successful payment capture:

* The client's address and billing contact must use a valid Indian postal address.
* The payment card must be from an Indian bank.
* The invoice must use INR as the currency.

To automatically convert invoice totals into other currencies upon payment in WHMCS:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''.
# Add <tt>INR</tt> as an [[Currencies#Adding.2FEditing_a_Currency|additional currency]].
# 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'''.
# Set '''Convert To For Processing''' on the Stripe gateway to ''INR''.

For more information about the additional Stripe requirements for Indian Stripe accounts, see [https://support.stripe.com/questions/requirements-for-india-export-charges Stripe's documentation].

{{modules}}

Cron Job Issues

2024-04-16T20:11:09Z

Lawrence: /* Segmentation fault */

{{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 does not directly relate 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 <tt>strace</tt> utility.

In some instances, the OpCache PHP extension causes this error. To determine if it is the cause, temporarily disable it by changing the cron job to the following command:

<source lang="php">php -q -d opcache.enable_cli=0 /path/to/whmcs/crons/cron.php</source>

If the error no longer occurs after making that change, we recommend reverting it and disabling the OpCache PHP extension on the server to resolve this.

===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}}

Disputes

2024-03-19T13:41:01Z

Lawrence: /* Stripe Disputes */

Disputes occur when a customer contests the charges you collect from their card issuer. Disputes can include chargebacks, inquiries, or retrievals, as well as other items, depending on the payment gateway you use. In WHMCS, you can update evidence and submit and close disputes.

You can access this feature at '''Billing > Disputes'''.

WHMCS 8.3 added support for disputes for Stripe (credit card only) and PayPal® Checkout transactions.

== The Dispute Process ==

Each card issuer or payment gateway handles disputes differently. For most card issuers and payment gateways, however, disputes follow the same general process:

# The customer submits the dispute to the card issuer or payment gateway.
# The card issuer or payment gateway notifies you of the dispute.
# In some scenarios, the card issuer or payment gateway will place a hold on the related funds.
# You can choose to provide evidence of the charge's validity, accept the dispute, or refund the payment.

Depending on the card issuer or payment gateway, some disputes may incur a fee.

== Dispute-Related Permissions ==

To work with disputes, admins must have the appropriate permissions, which the ''Full Administrator'' role includes by default:

* '''List Disputes''' — View the list of disputes.
* '''Manage Disputes''' — Submit evidence for, view evidence for, and manage the dispute.
* '''Close Disputes''' — Close disputes immediately.

== Responding to Disputes ==

WHMCS 8.3 added support for disputes for Stripe and PayPal® Checkout transactions. WHMCS 8.9 and later also include dispute support for [[PayPal Payments]] and [[PayPal Card Payments]].

To view details for a dispute, click on the view icon in the far-right column for that dispute. The displayed details for a dispute vary based on the payment gateway. They often include the dispute reason, dispute and transaction IDs, status, submitted evidence, and information about the customer and the actions taken during the dispute process.

<div class="docs-alert-warning">
<span class="title">Submitting Disputes</span><br />
Each payment gateway handles submitting evidence and disputes differently. Submitting a dispute is final.
</div>

=== Stripe Disputes ===

<div class="docs-alert-info">
WHMCS only supports disputes for the '''Stripe''' module. The '''Stripe ACH''' and '''Stripe SEPA''' modules do '''not''' support disputes.
</div>

The Stripe integration provides full features for managing disputes. Among other features, Stripe allows you to submit evidence directly through the WHMCS interface. Currently, other payment gateways do '''not''' support direct submission from within WHMCS. Before you submit a dispute, make certain that all of the displayed information is correct and that you have submitted all of your relevant evidence.

To submit evidence for a dispute:

# Under '''Submit Evidence''', choose one or more types of evidence from the '''Choose Evidence to Submit''' menu. Additional form fields will appear.
# Enter the evidence or upload files for each of the evidence types you selected.
# Click '''Update Evidence'''.

When you have finished adding evidence and are ready to submit your response to the dispute, click '''Submit Dispute'''.

=== PayPal Disputes ===

[[PayPal Checkout]], [[PayPal Payments]], and [[PayPal Card Payments]] do '''not''' allow you to submit evidence directly from within WHMCS. Instead, to submit evidence or submit the dispute, click '''Manage Dispute'''. WHMCS will direct you to PayPal, which will guide you through the evidence and submission process.

=== Closing a Dispute ===

When you close a dispute, it is immediately accepted and lost. This action is final.

When you do this, WHMCS will immediately relay this to the payment gateway, which will submit a full refund to the customer. WHMCS does '''not''' issue the refund itself. If you use a payment gateway that supports payment reversals, WHMCS must wait until your payment gateway notifies WHMCS, after which WHMCS will automatically return the payment.

<div class="docs-alert-warning">
<span class="title">Payment Reversals</span><br />
Whether WHMCS can reverse the payment depends on [[Payment_Reversals#What_does_it_do.3F|whether the payment gateway supports payment reversals]] and your current [[Automation Settings|settings]]. Currently, PayPal supports payment reversals but Stripe does not.
</div>

To close a dispute, click '''Close Dispute''' at the bottom of the page.

Disputes

2024-03-19T13:39:25Z

Lawrence:

Disputes occur when a customer contests the charges you collect from their card issuer. Disputes can include chargebacks, inquiries, or retrievals, as well as other items, depending on the payment gateway you use. In WHMCS, you can update evidence and submit and close disputes.

You can access this feature at '''Billing > Disputes'''.

WHMCS 8.3 added support for disputes for Stripe (credit card only) and PayPal® Checkout transactions.

== The Dispute Process ==

Each card issuer or payment gateway handles disputes differently. For most card issuers and payment gateways, however, disputes follow the same general process:

# The customer submits the dispute to the card issuer or payment gateway.
# The card issuer or payment gateway notifies you of the dispute.
# In some scenarios, the card issuer or payment gateway will place a hold on the related funds.
# You can choose to provide evidence of the charge's validity, accept the dispute, or refund the payment.

Depending on the card issuer or payment gateway, some disputes may incur a fee.

== Dispute-Related Permissions ==

To work with disputes, admins must have the appropriate permissions, which the ''Full Administrator'' role includes by default:

* '''List Disputes''' — View the list of disputes.
* '''Manage Disputes''' — Submit evidence for, view evidence for, and manage the dispute.
* '''Close Disputes''' — Close disputes immediately.

== Responding to Disputes ==

WHMCS 8.3 added support for disputes for Stripe and PayPal® Checkout transactions. WHMCS 8.9 and later also include dispute support for [[PayPal Payments]] and [[PayPal Card Payments]].

To view details for a dispute, click on the view icon in the far-right column for that dispute. The displayed details for a dispute vary based on the payment gateway. They often include the dispute reason, dispute and transaction IDs, status, submitted evidence, and information about the customer and the actions taken during the dispute process.

<div class="docs-alert-warning">
<span class="title">Submitting Disputes</span><br />
Each payment gateway handles submitting evidence and disputes differently. Submitting a dispute is final.
</div>

=== Stripe Disputes ===

The Stripe integration provides full features for managing disputes. Among other features, Stripe allows you to submit evidence directly through the WHMCS interface. Currently, other payment gateways do '''not''' support direct submission from within WHMCS. Before you submit a dispute, make certain that all of the displayed information is correct and that you have submitted all of your relevant evidence.

To submit evidence for a dispute:

# Under '''Submit Evidence''', choose one or more types of evidence from the '''Choose Evidence to Submit''' menu. Additional form fields will appear.
# Enter the evidence or upload files for each of the evidence types you selected.
# Click '''Update Evidence'''.

When you have finished adding evidence and are ready to submit your response to the dispute, click '''Submit Dispute'''.

=== PayPal Disputes ===

[[PayPal Checkout]], [[PayPal Payments]], and [[PayPal Card Payments]] do '''not''' allow you to submit evidence directly from within WHMCS. Instead, to submit evidence or submit the dispute, click '''Manage Dispute'''. WHMCS will direct you to PayPal, which will guide you through the evidence and submission process.

=== Closing a Dispute ===

When you close a dispute, it is immediately accepted and lost. This action is final.

When you do this, WHMCS will immediately relay this to the payment gateway, which will submit a full refund to the customer. WHMCS does '''not''' issue the refund itself. If you use a payment gateway that supports payment reversals, WHMCS must wait until your payment gateway notifies WHMCS, after which WHMCS will automatically return the payment.

<div class="docs-alert-warning">
<span class="title">Payment Reversals</span><br />
Whether WHMCS can reverse the payment depends on [[Payment_Reversals#What_does_it_do.3F|whether the payment gateway supports payment reversals]] and your current [[Automation Settings|settings]]. Currently, PayPal supports payment reversals but Stripe does not.
</div>

To close a dispute, click '''Close Dispute''' at the bottom of the page.

WHMCS cPanel Licensing Module

2024-02-07T13:06:14Z

Lawrence:

== About this Addon Module ==

<div class="docs-alert-warning">
<span class="title">Licensing Addon</span><br />
* The cPanel Licensing Automation module is not associated with the WHMCS [[Licensing Addon]].
* This module is for cPanel Partners. If you are not yet a partner, see [https://www.cpanel.net/partners/ the cPanel website].
</div>

The cPanel Licensing Automation module for WHMCS is a tool that utilizes the cPanel Manage2 API to provide an automated solution for cPanel Partners to provision, manage, and bill for cPanel & WHM licenses.

For help to get started, see [[WHMCS cPanel Licensing Module Getting Started Guide]].

<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;">WHMCS cPanel Licensing Module</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:darkred;">No</td>
</tr>
</table>

== Activating WHMCS cPanel Licensing Module ==

You will need to download and upload the module before you can activate the addon through the Admin Area.

# Download the latest version from [https://marketplace.whmcs.com/product/4993 the WHMCS Marketplace].
# Extract the zip file.
# Upload the <tt>cpanellicensing</tt> directory to the <tt>/modules/addons</tt> folder of your WHMCS installation.
# 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 '''cPanel Licensing'''.
# Click '''Configure'''.
# Select the admin role groups who will have access to this addon.
# Select the admin users who can configure settings within the addon.
# Click '''Save Changes'''.

== Using WHMCS cPanel Licensing Module ==

[[File:CPLic_AuthenticatingIntoManage2.png|thumb|Manage2 Login Prompt]]

After configuring the module, you will need to authenticate into Manage2.

To do this, navigate to '''Addons > cPanel Licensing''' and log in using your Manage2 username and password. The system will import your Manage2 data into WHMCS. This may take several minutes depending on the amount of licenses associated with the Manage2 account.

=== Autoscale ===

'''Autoscale''' allows the cPanel Licensing addon module to dynamically adjust a service's configurable option based on the number of accounts associated with its cPanel license. Use the Autoscale settings below when you want WHMCS to automatically upgrade a license to the next tier based on usage.

Autoscale uses the following procedure:

# A server administrator provisions an extra cPanel account which in turn pushes the server into the next cPanel license tier.
# cPanel's Manage2 software detects this and changes the license tier for billing purposes in the cPanel Partner account.
# WHMCS performs a synchronisation with Manage2 at specific intervals that picks up this change.
# The Control Panel configurable option in WHMCS changes to match the new cPanel license tier and as a result of this, the service price is auto recalculated to include the additional cost of the new license tier.
# The next renewal invoice generated by the service (per the Next Due Date) will reflect the new cPanel license tier.

This ensures that the client is always billed appropriately for their current cPanel license tier without any manual intervention.

=== Settings ===

[[File:CPLic_Settings.png|thumb|Settings Tab]]

The cPanel Licensing addon offers further configuration settings concerning Data and API Permissions, as well as Invoice and Cart Display Options.

These can be accessed by navigating to '''Addons > cPanel Licensing''', and then clicking on the '''Settings''' tab. The settings seen on this page are detailed below.

==== Data and API Permissions ====

*'''Manage2 Account''' - Your Manage2 Registered Email. Here you will see the logged in user and a '''Logout''' button.
*'''Provisioning Default Group''' - The default group to assign new licenses to.
*'''Permissions''' - Access controls for functionality within this addon.

==== Invoice and Cart Display Options ====

*'''Invoicing Line Item Format''' - The line item description used for invoicing by packages that offer bulk cPanel accounts.
*'''Option Info Tooltip''' - Optional tooltip text to display near license configurable options during checkout. HTML is supported.
*'''Option Description Format''' - The configurable option selection format for display on the order form for packages that offer bulk cPanel accounts.
*'''Autoscale Label''' - The label to be displayed on the order form.
*'''Autoscale Notification Email''' - The email template to be sent upon an autoscale change. For more information, see the [[WHMCS cPanel Licensing Module#Autoscale Notification Email|Autoscale Notification Email]] section.

==== Autoscale Notification Email ====

The cPanel Licensing module can be configured to send a custom email notification to a client upon an Autoscale Change.

To configure this functionality you will need to first create the custom email to be used. You can do this at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Email Templates]]''' or, prior to WHMCS 8.0, '''Setup > Email Templates'''. This custom email template type must be either '''Product/Service Messages''' or '''Notification Messages'''.

The custom template to be used will have access to the following merge fields:

*'''newOption''' - The display name of the configurable option being upgraded to.
*'''oldOption''' - The display name of the configurable option being upgrade from.
*'''isUsageUpgrade''' - A boolean indicating whether or not the upgrade is due to usage activity.

Once the custom email template has been created, it can be set as the ''Autoscale Notification Email'' template.

To do this:

# Go to '''Addons > cPanel Licensing'''.
# Click on the '''Settings''' tab.
# Locate the '''Autoscale Notification Email''' setting.
# Select the custom email template from the menu.
# Click '''Save Changes'''.

=== Pricing ===

[[File:CPLic_Pricing.png|thumb|Pricing Tab]]

cPanel licenses are sold as configurable options of products. This interface allows you to set pricing for those options as well as respective metric pricing for cPanel accounts.

Typically the configurable option would be assigned to a product with which a cPanel license would beneficial; a VPS or Dedicated Server. It can also be sold as a [[#Standalone_Product|standalone product]].

On this tab you will see the ''ID'', ''Configuration Name'', ''Selections'', and ''Auto-Scale'' columns displayed for each option that has been created with, or imported into, the cPanel Licensing addon.

Additionally, you will see buttons labelled ''New'', ''Import'', and ''Manage'' which allow you to create, import, and manage options respectively. The functionality of these buttons is detailed below.

==== Create New Option ====

[[File:CPLic_CreateNewOption.png|thumb|Create New Option Modal]]

Clicking on the ''New'' button will bring up the ''Create New Option'' modal. It is within this modal that you can create a new [[Configurable Options|configurable option]] to be used for offering cPanel licenses to your customers via this module.

The following configuration settings are displayed on this modal:

*'''Parent Group''' - The option group to create the new option within. Should the ''Create New Group'' option be selected, then the ''Group Name'' option will appear.
*'''Group Name''' - The name for the new configurable option group. This option will only appear when the ''Create New Group'' option has been selected from the ''Parent Group'' drop-down menu.
*'''Option Name''' - The display name for the new configurable option.
*'''Option Type''' - The type to be used by the new configurable option. Only drop-down and radio option types are supported.
*'''Auto-Populate''' - Automatically populate the new option with the default cPanel license package offerings and recommended retail pricing.
*'''Hardware Type''' - Offers a selection between the ''Dedicated/Metal'' and ''VPS/Cloud'' options.
*'''Default Visibility''' - Toggles whether or not the option is visible from the Order Form.

Once the settings have been completed, clicking on the ''Create'' button will generate the Configurable Option Group, create Configurable Options if the ''Auto-Populate'' option was selected, and display the option group in the Pricing tab of the module.

==== Import Existing Option ====

[[File:CPLic_ImportExistingOption.png|thumb|Import Existing Option Modal]]

If you have an existing '''Configurable Option Group''' and '''Configurable Options''' that you would like to be used for the provisioning and billing of cPanel licenses, then these can be imported for use with the cPanel Licensing addon.

During this process you will be prevented with a list of configurable options, and be asked to associate them with a cPanel Package. If a configurable option is not related to a cPanel license, then leave the dropdown at the ''Not a cPanel License Option'' value. Options left at this value will not be used by the cPanel Licensing module, and will continue to function as a normal configurable option.

<div class="docs-alert-warning">Only ''Dropdown'' or ''Radio'' configurable options are supported for import. Other option types will not be available for import.</div>

Clicking on the ''Import'' button will bring up the ''Import Existing Option'' modal. It is within this modal that you can import an existing configurable option to be used for the provisioning and billing of cPanel licenses via this module.

Within the ''Import Existing Option'' modal you will be presented with the ''Option Name'' drop-down menu. This menu allows you to select which Configurable Option you would like to import.

Selecting the desired option from the drop-down and clicking the ''Continue'' button will bring you to the ''Configure Import'' section. Here you will see a list of ''Selectable Options'' displayed. For each selectable option, please select a cPanel Package below that it relates to. If an option is not related to a cPanel license, leave the dropdown at the default value.

Clicking the ''Import'' button will import the configurable options into the module, and make them available for further configuration via the ''Pricing'' tab.

====Option & Price Management====

[[File:CPLic_OptionPriceManagement.png|thumb|Option & Price Management Modal]]

Within the ''Manage'' column for each associated option a button with a wrench icon exists. This is the ''Manage'' button, and clicking on this button will bring up the ''Option & Price Management'' modal. It is within this modal that you can modify options within the group, as well as modify the cPanel related options themselves.

This modal is made up of three elements: the ''Configurable Option Settings'' section in the top-left, the ''Selectable Options'' section in the bottom-left, and the ''Selectable Option Content'' panel on the right.

===== Configurable Option Settings =====

The '''Configurable Option Settings''' section provides the ability to alter the ''Configurable Option Type'', and toggle both the ''Visibility'' and ''Autoscale'' Option.

The '''Autoscale Option''' toggle allows the cPanel Licensing addon module to dynamically adjust a service's configurable option based on the number of licenses associated with its cPanel account. This should be used when you want WHMCS to automatically upgrade a license to the next tier based on usage. Enabling this option requires that all configurable options associated with a cPanel Package have pricing configured.

All changes made in this section are automatically saved.

===== Selectable Options =====

The '''Selectable Options''' section displays the full list of existing configurable options, and offers the ability to create new options via the ''Add Option'' button. Clicking on an option from this list will display that option's content within the ''Selectable Option Content'' panel.

Additionally, in Version 7.7 and later, dragging the options allow you to rearrange their order as desired. All changes made in this section are automatically saved.

===== Selectable Option Content =====

The '''Selectable Option Content''' section provides both an overview of that option, as well as the ability to configure it further. The ''Name'', ''Visibility'', and ''Package'' details are immediately displayed at the top, and can all be altered as desired. Additionally, the ''Configurable Option ID'' is displayed in the top-left corner.

The Pricing section is offers the ability to configure pricing for the option. Here the ''Base Recurring'', and ''Setup Fee'' values can be modified. The ''Metric: cPanel Accounts'' and ''Threshold'' values can also be modified for packages that support them.

The ''Auto populate other billing cycles based on monthly pricing'' toggle will render the Billing Cycle tabs un-clickable and will automatically populate their pricing based on the pricing present in the Monthly pricing tab.

Changes to this section are not automatically saved, and clicking on the ''Save'' button will commit the changes. Inversely, clicking on the ''Delete'' button will delete the configurable option.

===== Metric: cPanel Accounts =====

The '''Metric: cPanel Accounts''' setting is displayed when configuring pricing for packages that offer an unlimited number of cPanel accounts. This setting provides the ability to set a per-account value that the customer will be billed for, as well as a threshold to define the number of accounts a customer must have before they are billed on a per-account basis.

When a customer orders a package, with the ''Metric: cPanel Accounts'' offering, a snapshot of the current price is taken. This snapshot is then stored, and used when generating renewal invoices for the customer's service in the future. This is done to ensure that changes can be made to a package's metric pricing without affecting existing customer orders.

If you need to ensure that the pricing snapshot is updated to the current metric pricing, then this can be achieved by selecting the [[Clients:Products/Services_Tab#Auto_Recalculate_on_Save|''Auto Recalculate on Save'']] checkbox and saving the service. This will see the existing snapshot discarded, and a new one created with the current metric pricing for the associated package.

The cPanel Licensing Addon retrieves the cPanel account value from the cPanel licensing system (Manage2) at the time of invoice generation. This is to ensure use of the most accurate value relative to Manage2, to which the license reseller is accountable. Manage2 doesn't provide the historical data necessary to calculate any prior month's usage. At this time, the cPanel Licensing Addon doesn't have historical snapshot capabilities that can augment this canonical data source.

The ''Auto Recalculate on Save'' option will continue to function as normal. When used a service's ''Recurring Amount'' will be populated with current pricing based on the service and configurable options selected.

====Standalone Product====

To present a standalone product that provisions a cPanel license, use the cPanel licensing module with the Auto Release provisioning module:

# 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'''.[[File:Cpanel standalone2.png|thumb|Configure Pricing]]
#Click '''Create a New Product'''.
#Select '''Other''' for '''Product Type'''.
#Enter a '''Product Name'''.
#Select ''Auto Release'' for '''Module Name'''.
#Click '''Continue'''.
# Select the '''Pricing''' tab.
#Choose '''Recurring''' for '''Payment Type'''.[[File:Cpanel standalone3.png|thumb|Configure the Auto Release Module]]
# Check the checkboxes in the '''One Time/Monthly''' column.
#Specify '''Setup''' and '''Price''' values of <tt>0.00</tt>.
#Select the '''Module Settings''' tab.
#Choose the '''Automatically setup the product as soon as the first payment is received''' option.
#Select the '''Configurable Options''' tab.
#Click the configurable option group for the cPanel license types. The cPanel Licensing Addon [[#Pricing|creates this]].
#Configure any other options are desired.
#Click '''Save Changes'''.

When this product is ordered, clients will be presented with the cPanel License Tier configurable option at the product configuration stage of the shopping cart and a license provisioned upon payment. The price of the configurable option will form the amount invoiced to the client each month.

===Manage2 Data===
The data imported from Manage2 is displayed within the module itself. This information is located within the ''Licenses'', ''Groups'', and ''Packages'' tabs. This allows you to quickly review and action your Manage2 data without leaving WHMCS.

====Licenses====
[[File:CPLic_Manage2DataLicenses.png|thumb|Licenses Tab]]

Licenses are associated with a clients' services. This interface allows modification of the license data stored at Manage2. The WHMCS data can be managed at the linked service.

On this tab you will see ''License ID'', ''Package/Group'', ''IP/Hostname'', ''Assigned Service'', and ''Status'' columns displayed for each license associated with your Manage2 account.

The '''Actions''' column offers the ability to perform the following actions against the associated license.

*'''Assign License''' - Assign the license to an existing service. More information can be found in the [[WHMCS cPanel Licensing Module#Assign License & Link to Existing License|Assign License & Link to Existing License]] section.
*'''Change IP''' - Change the license's IP Address.
*'''Change group''' - Change the license's Group.
*'''Change package''' - Change the license's Package.
*'''Expire''' - Expire the license within Manage2.
*'''View License Details''' - Review a detailed output of license information.

====Groups====
[[File:CPLic_Manage2DataGroups.png|thumb|Groups Tab]]

Groups are arbitrary categories. They are unique to your Company. They can help keep your licenses organised by modeling how you sell and manage the product-customer lifecycle.

On this tab you will see the ''Group ID'', ''Name'', ''Attributes'', and ''Licenses'' columns displayed for each group associated with your Manage2 account.

The '''Actions''' column offers the ability to perform the following actions against the associated group.

*'''Change name''' - Change the group's name within Manage2.
*'''Change tax status''' - Change the group's tax status within Manage2.
*'''Show Licenses''' - Display a filtered list of licenses associated with the specific group.

====Packages====
[[File:CPLic_Manage2DataPackages.png|thumb|Packages Tab]]

Packages are SKUs. They represent the product, features, or bundled options that are granted to the license holder.

On this tab you will see the ''Package ID'', ''Name'', ''Attributes'', and ''Licenses'' columns displayed for each package associated with your Manage2 account.

The ''Actions'' column offers the ability to perform the following actions against the associated package.

*'''Show Licenses''' - Display a filtered list of licenses associated with the specific package.

===Service Management===
[[File:CPLic_ServiceManagement.png|thumb|cPanel Licensing Service Panel]]

Services associated with a cPanel Licensing related Option Group will see a panel labeled ''cPanel Licensing'' when viewing that service via the Admin Area.

When a service is associated with a cPanel license, an overview if the license details is displayed along with the following buttons:

*'''Sync IP''' - Change the license's IP Address to the value displayed in the ''Dedicated IP'' field or ''IP Address'' custom field.
*'''Sync Package''' - Change the license's Package to the value displayed in the cPanel Licensing configurable option.
*'''View Details''' - Display a modal containing the cPanel License Information.
*'''Expire''' - Expire the license within Manage2.

The following buttons will be displayed within the panel at all times:

*'''Provision New cPanel License''' - Automatically provision a new license from Manage2 using the package displayed in the cPanel Licensing configurable option and the IP address displayed in the ''Dedicated IP'' field or ''IP Address'' custom field.
*'''Link to Existing License''' - Display a modal that allows for the search of existing licenses to be assigned to the service. More information can be found in the [[WHMCS cPanel Licensing Module#Assign License & Link to Existing License|Assign License & Link to Existing License]] section.

===Handling Manual License Cancellations===
Expiring a license, either by clicking '''Expire''' in the '''[[Clients:Products/Services_Tab|Products/Services]]''' tab of the client profile or in Manage2, does not automatically update the '''Recurring Amount''' for the parent service. The system cannot determine whether to bill a license using the license's state.

To cancel a license and ensure that the system updates the '''Recurring Amount''' value correctly:
# Click '''Expire''' in the '''Service Management''' section.
# Set the parent service's [[WHMCS cPanel Licensing Module#Configurable Option Settings|configurable option]] to ''None''.
# Set '''Recalculate on Save''' to ''ON''.
# Click '''Save Changes'''.

The system will update the parent service's '''Recurring Amount''' to no longer include the cost of the expired license.

===Assign License & Link to Existing License===
[[File:CPLic_AssignLicense.png|thumb|Assign License Modal]]
[[File:CPLic_LinkExistingLicense.png|thumb|Link to Existing License Modal]]

Both the Licenses tab, seen on the cPanel Licensing module page, and the cPanel Licensing panel, seen on the Service page, offer the ability to manually assign a service to a license and vice versa.

The '''Assign License''' modal provides a searchable drop-down menu that can be used to locate and select the desired service. Once the service has been selected, clicking on the ''Assign'' button will assign the service to that specific license.

The '''Link to Existing License''' modal provides a searchable drop-down menu that can be used to locate and select the desired license. Once the license has been selected, clicking on the ''Assign'' button will assign the license to that specific service.

In both cases, it is important to note that the configurable option will not be automatically selected. You must navigate to the Service page in the Admin Area, set the configurable option to coincide with the appropriate package if fixed, or enable the autoscale option if applicable. '''This is necessary for automated billing to occur.'''

Additionally, only a singular active license can be assigned to a service. Using the ''Link to Existing License'' or ''Assign License'' functionality to assign a new license to a service already in possession of an active license will result in the replacement of that active license. In this instance, a prompt will appear to confirm this action.

===Updating Manage2 Account Credentials===

The cPanel Licensing Addon uses your Manage2 username and password to authenticate with the Manage2 API. To facilitate this, the system encrypts and stores your Manage2 credentials in WHMCS's database. Because updating your credentials in Manage2 does not automatically trigger an update in WHMCS, the system will no longer be able to successfully authenticate requests.

After updating your Manage2 credentials, ensure that the system can communicate with Manage2:

# In the Admin Area, go to '''Addons > cPanel Licensing''' and click on the '''Settings''' tab.
# In the '''Manage2 Account''' section, click '''Logout'''.
# Log in using your Manage2 account credentials.

After successfully logging in, the system will store your new Manage2 login details in the database.

== Upgrading ==

If you have an earlier version of the cPanel Licensing Module installed, follow the steps below:

# Download the latest version from [https://marketplace.whmcs.com/product/4993 the WHMCS Marketplace].
# Extract the zip file.
# Upload the 'cpanellicensing' directory to the '/modules/addons' folder of your WHMCS installation.

==Troubleshooting==
This section covers the error messages which may be encountered during license assignment.

===A license was deactivated on the same IP last month before billing could occur===
This response indicates that the previous cPanel license associated with the service's IP address accrued usage, and was deactivated before billing could occur within Manage2.

A reactivation fee must be paid before a new license can be provisioned for that IP address. This must be done via Manage2 directly.

===This license is already assigned to another service===
Review the '''Addons > cPanel Licensing''' page to see the current service to which the license is assigned in WHMCS.

Click the ''Assign'' button a second time to remove the current assignment and assign to the current service.

===You cannot assign a license to this service===
'''You cannot assign a license to this service as the product to which it is assigned does not have a configurable option for a cPanel license'''

There is no license pricing configuration assigned to the product in use, a license can only be assigned when a pricing scheme is associated with the product. The following steps will make the necessary adjustments to the product/service configuration:

# Navigate to the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab for the service.
# Check whether the cPanel Licenses configurable option appears. If it does not:
## Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Configurable Options]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Configurable Options'''.
## Click '''Edit''' for the cPanel licensing option group.
## Press Ctrl + Click to select all the applicable products that will offer a cPanel license option. Make certain to select the product that is currently exhibiting the error.
## Click '''Save Changes'''.
# If the cPanel License configurable option is displayed, select the desired cPanel license tier.
# Click '''Save Changes'''.
# Use the '''Assign''' or '''Link''' buttons again to complete the task successfully.

===cPanel Licensing options of product are not set for this service===

'''cPanel Licensing options of product are not set for this service. Review and save the cPanel licensing options for this service and try again'''

A license pricing configuration is assigned to the product in use, but the desired option has not been selected for the individual service record. WHMCS needs to know the desired license tier to invoice the client correctly.

The following steps will make the necessary adjustments to the service record:

# Go to the client's '''[[Clients:Products/Services Tab|Products/Services]]''' tab for the service.
# Use the cPanel License configurable option to select the desired cPanel license tier.
# Click '''Save Changes'''.
# Use the '''Assign''' or '''Link''' buttons again to complete the task successfully.

== Change Log ==

''N/A''

Administrator Roles

2023-11-17T19:48:48Z

Lawrence: /* Create or Update an Administrator Role */

Administrator roles allow you to set the permissions for different types of admins. You can manage roles in the WHMCS [[Admin Area]].

You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Administrator Roles'''.

For more information about creating and managing admins, see [[Administrator Users]].

==Administrator Roles==

You can set up as many different administrator roles as you want and then assign your admins to them.

WHMCS includes three default roles: '''Full''', '''Sales''', and '''Support Only'''.

==Create or Update an Administrator Role==

To create or update an administrator role:

# Create or edit a new role:
#* To create a new role, click '''Add New Role Group''' link and enter a name for it.
#* To edit a role, click the edit icon for that role. A list of permissions settings will appear.
# For '''Permissions''', check the desired permissions. <div class="docs-alert-success">For all admin roles, you '''must''' enable '''Support Center Overview''' or '''Main Homepage'''. This allows the admin to see the support center overview or admin summary pages after logging in.</div>
#* '''Manage''' permissions allow you to manage an item.
#* '''View''' permissions allow you to view an item.
#* '''Create''' permissions allow you to create a new item.<div class="docs-alert-warning"><span class="title">Access Denied</span><br />Many '''Create''' permissions require the related '''Manage''' permission. If you see '''Access Denied''' errors, add the '''Manage''' permission. For example, errors will occur for '''Create Invoice''' if you don't also enable '''Manage Invoices'''.</div>
#* '''Configure''' permissions are generally for settings under '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings''' or, prior to WHMCS 8.0, '''Setup'''.
# For '''Reports Access Controls''':
#* Select '''Unrestricted''' to allow access to all reports at '''Reports > [[Reports]]'''.
#* Select '''Restrict Access''' to only allow access to specific reports. Then, check the desired reports.
# For '''Email Messages''', check the email types that you want admins with that role to receive.
#* '''System Emails''' includes notifications of the domain sync, daily cron activity, POP/IMAP import errors, failed admin login attempts, and when the WHMCS license is nearing client limits (if they apply).
#* '''Account Emails''' includes notifications of new orders, client profile changes, automatic provisioning of ordered items (with any error messages), and client-initiated offline direct debit payments (when using the '''[[Direct_Debit|Direct Debit]]''' payment gateway).
#* '''Support Emails''' includes notifications of new support tickets, replies to existing tickets, and changes to them. The specific notifications that the system sends will depend on admins' assigned support departments, if they are watching the ticket, or if they are flagged on the ticket. For a list of notifications and who will receive them, see [[Support_Tickets#Notifications|Notifications]].
# Click '''Save'''.

You can then assign the administrator role to an admin at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Administrator Users]]''' or, prior to WHMCS 8.0, '''Setup > Staff Management > Administrator Users'''.

===Role Permissions===

The system provides options for Admin Area actions and email receiving preferences for system emails, account emails, and support emails.

For an admin user who works with clients and tickets, grant the '''Manage''' and '''View''' permissions for tickets, domains, and client products. If they will be processing client orders or creating new services for clients, also grant the applicable '''Create''' and '''Manage''' permissions.

If an admin will provide remote support and you only want them to view items but not change them, you can grant them the desired '''View''' permissions only.

==Recommendations and Common Role Configurations==

===Limiting access to a specific installed addon===

This is commonly required for allowing third party developers limited access to the WHMCS admin area in order to debug an issue with an installed addon module. For addon modules, the '''Addon Modules''' permission will need to be enabled and then the '''Access Control''' setting on the applicable addon will need to be edited under '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Addon Modules]]''' to give their admin user access to the addon under the Addons menu (if applicable).

Depending on how the addon operates, it may be necessary to enable additional permissions as well (at discretion). For example: if an addon adds a "Support PIN" number on the client summary page, enabling the '''View Clients Summary''' permission may be necessary for the developer to be able to access a test client and verify it is working as expected.

===Debugging provisioning modules===

For debugging provisioning modules, it may be helpful to enable the '''Configure Servers''', '''View Clients Products/Services''', '''View Module Debug Log''', and '''Perform Module Command Operations''' permissions so that the developer is able to ensure the underlying module is correctly configured, test with a test service and obtain any module log data (if their module supports it). Further permissions, such as the ability to edit services with '''Edit Clients Products/Services''', are generally not recommended and should only be considered on a case-by-case basis.

==Managing Two Factor Authentication==

Two-factor authentication adds an additional layer of security by introducing a second step to the login process. It takes something you know (for example, your password), and adds a second factor, typically something you physically have (such as your phone). Since the system will require both to log in, if an attacker obtains your password, two-factor authentication would stop them from accessing your account.

You can apply [[Two-Factor Authentication]] to staff, clients, or both. Instructions for configuring Two-Factor Authentication are on the [[Security_Modules#Configuration|Security Modules page]].

Administrator Roles

2023-11-17T19:48:20Z

Lawrence: /* Create or Update an Administrator Role */

Administrator roles allow you to set the permissions for different types of admins. You can manage roles in the WHMCS [[Admin Area]].

You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Administrator Roles'''.

For more information about creating and managing admins, see [[Administrator Users]].

==Administrator Roles==

You can set up as many different administrator roles as you want and then assign your admins to them.

WHMCS includes three default roles: '''Full''', '''Sales''', and '''Support Only'''.

==Create or Update an Administrator Role==

To create or update an administrator role:

# Create or edit a new role:
#* To create a new role, click '''Add New Role Group''' link and enter a name for it.
#* To edit a role, click the edit icon for that role. A list of permissions settings will appear.
# For '''Permissions''', check the desired permissions. <div class="docs-alert-success">For all admin roles, you '''must''' enable '''Support Center Overview''' or '''Main Homepage'''. This allows the admin to see the support center overview or admin summary pages after logging in.</div>
#* '''Manage''' permissions allow you to manage an item.
#* '''View''' permissions allow you to view an item.
#* '''Create''' permissions allow you to create a new item.<div class="docs-alert-warning"><span class="title">Access Denied</span><br />Many '''Create''' permissions require the related '''Manage''' permission. If you see '''Access Denied''' errors, add the '''Manage''' permission. For example, errors will occur for '''Create Invoice''' if you don't also enable '''Manage Invoices'''.</div>
#* '''Configure''' permissions are generally for settings under '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings''' or, prior to WHMCS 8.0, '''Setup'''.
# For '''Reports Access Controls''':
#* Select '''Unrestricted''' to allow access to all reports at '''Reports > [[Reports]]'''.
#* Select '''Restrict Access''' to only allow access to specific reports. Then, check the desired reports.
# For '''Email Messages''', check the email types that you want admins with that role to receive.
# For '''Email Messages''', check the email types that you want admins with that role to receive.
#* '''System Emails''' includes notifications of the domain sync, daily cron activity, POP/IMAP import errors, failed admin login attempts, and when the WHMCS license is nearing client limits (if they apply).
#* '''Account Emails''' includes notifications of new orders, client profile changes, automatic provisioning of ordered items (with any error messages), and client-initiated offline direct debit payments (when using the '''[[Direct_Debit|Direct Debit]]''' payment gateway).
#* '''Support Emails''' includes notifications of new support tickets, replies to existing tickets, and changes to them. The specific notifications that the system sends will depend on admins' assigned support departments, if they are watching the ticket, or if they are flagged on the ticket. For a list of notifications and who will receive them, see [[Support_Tickets#Notifications|Notifications]].
# Click '''Save'''.

You can then assign the administrator role to an admin at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Administrator Users]]''' or, prior to WHMCS 8.0, '''Setup > Staff Management > Administrator Users'''.

===Role Permissions===

The system provides options for Admin Area actions and email receiving preferences for system emails, account emails, and support emails.

For an admin user who works with clients and tickets, grant the '''Manage''' and '''View''' permissions for tickets, domains, and client products. If they will be processing client orders or creating new services for clients, also grant the applicable '''Create''' and '''Manage''' permissions.

If an admin will provide remote support and you only want them to view items but not change them, you can grant them the desired '''View''' permissions only.

==Recommendations and Common Role Configurations==

===Limiting access to a specific installed addon===

This is commonly required for allowing third party developers limited access to the WHMCS admin area in order to debug an issue with an installed addon module. For addon modules, the '''Addon Modules''' permission will need to be enabled and then the '''Access Control''' setting on the applicable addon will need to be edited under '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Addon Modules]]''' to give their admin user access to the addon under the Addons menu (if applicable).

Depending on how the addon operates, it may be necessary to enable additional permissions as well (at discretion). For example: if an addon adds a "Support PIN" number on the client summary page, enabling the '''View Clients Summary''' permission may be necessary for the developer to be able to access a test client and verify it is working as expected.

===Debugging provisioning modules===

For debugging provisioning modules, it may be helpful to enable the '''Configure Servers''', '''View Clients Products/Services''', '''View Module Debug Log''', and '''Perform Module Command Operations''' permissions so that the developer is able to ensure the underlying module is correctly configured, test with a test service and obtain any module log data (if their module supports it). Further permissions, such as the ability to edit services with '''Edit Clients Products/Services''', are generally not recommended and should only be considered on a case-by-case basis.

==Managing Two Factor Authentication==

Two-factor authentication adds an additional layer of security by introducing a second step to the login process. It takes something you know (for example, your password), and adds a second factor, typically something you physically have (such as your phone). Since the system will require both to log in, if an attacker obtains your password, two-factor authentication would stop them from accessing your account.

You can apply [[Two-Factor Authentication]] to staff, clients, or both. Instructions for configuring Two-Factor Authentication are on the [[Security_Modules#Configuration|Security Modules page]].

Google reCAPTCHA

2023-10-31T20:11:40Z

Lawrence: /* Captcha Locations */

Differentiating between humans and bots (computers) is an ever-changing and more challenging task. A number of solutions have been implemented, typically involving increasing obscured text and numbers or images, such as the default 5 character verification of WHMCS.

As bots and software have become more sophisticated, a common solution was to make the text more difficult to read, which can result in frustrated and lost potential clients. Google's reCAPTCHA set's out to change that. They have created a system that is easy for people, but hard for bots. By using an advanced and more secure risk analysis engine, humans and bots are more effectively differentiated.

The first step in authentication is to ask the user to confirm that they are not a robot by checking a checkbox. Google's risk analysis engine analyzes how the user checked the checkbox, including how the user responds before, during, and after the action. In cases where the engine cannot confidently differentiate between them, a mobile-friendly verification tool like a CAPTCHA or image selection from a list may appear.

* Google reCAPTCHA V2 is available in WHMCS 7.0 and later.
* Google Invisible reCAPTCHA is available in WHMCS 7.7 and later.

==Enabling Google reCAPTCHA==

Google's reCAPTCHA may be enabled by following these steps:

# Go to the '''[[Security_Tab|Security]]''' 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'''.
# For '''Captcha Type''', select '''reCAPTCHA v2'''.
# [https://www.google.com/recaptcha/admin Log in to your Google account .]
# Select '''"I’m not a robot" Checkbox'''.
# Enter your domain under the '''domains''' section.
# Accept the Google terms of service.
# Click '''Register''' to finish registering your site and generating your keys.
# Copy the '''Site Key''' and '''Secret Key''' issued by Google and enter them in the fields provided in WHMCS.
# Click '''Save Changes'''.

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

==Enabling Invisible reCAPTCHA==
To enable the Invisible reCAPTCHA feature for the shopping cart, follow these steps:
[[File:Recaptcha-configuration.png|thumb|reCAPTCHA Key Generation]]

# Go to the '''[[Security Tab|Security]]''' 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'''.
# For '''Captcha Type''', select '''Invisible reCAPTCHA'''.
# [https://www.google.com/recaptcha/admin Log in to your Google account .]
# Enter a label for your key.
# Select '''reCAPTCHA v2'''.
# Select '''Invisible reCAPTCHA badge'''.
# Enter your domain under the '''domains''' section.
# Accept the Google terms of service.
# Click '''Register''' to finish registering your site and generating your keys.
# Copy the '''Site Key''' and '''Secret Key''' issued by Google and enter them in the fields provided in WHMCS.
# Click '''Save Changes'''.

==Captcha Locations==
<div class="docs-alert-info"><i class="fa fa-question-circle"></i> This page describes a feature available in version 7.7 and above</div>

You can choose which forms have a captcha enabled on them by checking the appropriate boxes in "Captcha for Select Forms". The following options are available:

* Shopping Cart Checkout - On checkout in the Client Area
* Domain Checker - The homepage domain checker, and on the Register or Transfer domain pages in the cart
* Client Registration - register.php
* Contact Form - contact.php
* Ticket Submission - When submitting a ticket
* Login Forms - Admin and Client login forms

==Troubleshooting==
===Invalid Site Key/I can't login===
If the site key specified under General Settings isn't valid for some reason and is preventing logins to the admin area to correct it, it will be necessary to disable reCAPTCHA manually via the database (setting "Captcha Form Protection " to "Always Off" temporarily to resolve this. Please take a backup of the database and then run the following SQL query using a tool like phpMyAdmin to do so:

<source lang="sql">
UPDATE tblconfiguration SET value = '' WHERE setting = 'CaptchaSetting';
</source>

Database Backups

2023-10-18T14:35:11Z

Lawrence: /* cPanel Backup */

Regular backups help to protect your customer data and WHMCS configuration, and they are vital if you run into certain prolems. WHMCS can automatically back up your database and upload it to a SFTP/FTP location or email it to a designated email address. You can also request a full cPanel backup for a specific user as part of the automatic backup process.

You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Database Backups'''.

<div class="docs-alert-info">
We added automated backups in WHMCS 7.3.
</div>

==Enable Automatic Backups==

To enable automatic backups for your WHMCS installation:

# Choose a backup option by clicking the correct heading: '''SFTP/FTP Backup''', '''cPanel Backup''', or '''Daily Email Backups'''.<div class="docs-alert-warning"><span class="title">Connection Tests</span><br />The '''SFTP/FTP Backup''' and '''cPanel Backup''' options require a successful connection test before activation. A connection test ensures that the details are valid and the WHMCS installation can connect to the server. Any connection issue allows a resolution before a backup attempt occurs, incurring less chance of a failed connection.</div>
# Enter the necessary informaton for that option. For more information on each option, see the sections below.
# Click '''Test Connection''' or '''Save & Activate'''.

===SFTP/FTP Backup===

The '''SFTP/FTP Backup''' option only supports FTP and SFTP. Other protocols, like FTPS and FTP/TLD, are unsupported.

This backup type stores the WHMCS-generated zipped SQL file on the specified remote server. Check "'Use Secure FTP/SFTP (Recommended)'" to ensure that the backup upload is completed using an SFTP connection.

====FTP Destination====

The '''FTP Destination''' value is relative to the login folder for the FTP/SFTP account you are using. For example, if, when you log in using your FTP details, the folder is <tt>/home/user/</tt> and the backup will be in <tt>/home/user/backups</tt>, enter <tt>backups/</tt> as the '''FTP Destination''' value.

If you intend to upload the backup file to the login folder, leave this field empty.

===cPanel Backup===

The '''cPanel Backup''' option uses the backup API functions that cPanel & WHM provides to generate backups using an API token.

API tokens in cPanel & WHM allow you to restrict the actions that an API token can perform. To do this, you must create a token with the following permissions in WHM at '''Development >> Manage API Tokens''':

<table class="table table-striped">
<tr>
<td>basic-whm-functions</td>
<td>cpanel-api</td>
</tr>
</table>

====cPanel Username====

When you enter your cPanel account information, the '''cPanel Username''' value is the name of the account that hosts your WHMCS installation.

====Backup Destination====

You can select the following '''Backup Destination''' options:

* '''Remote FTP Server''' — Select this option to use FTP to store the backup file on a remote server.
* '''Remote FTP Server (Passive connection)''' — Select this option to use passive FTP to store the backup file on a remote server.
* '''Secure Copy (SCP)''' — Select this option to use SCP to store the backup file on a remote server.
* '''Home Directory''' — Select this option to save the backup file to the server.

<div class="docs-alert-warning"><i class="fa fa-exclamation-triangle"></i>Using '''Home Directory''' will generate the backup file in the cPanel user's home directory. This will count against any disk space limits, and you should manually move it to a better location after completion.</div>

The system cron job will only request the start of a full backup. Completion and relocation of the backup occurs within cPanel, and WHMCS will not notify you about the process.

===Daily Email Backups===

This backup option may fail to complete successfully with large databases due to system memory or time execution limits. We do not recommend this method for larger installations.

==Disable Automatic Backups==

To disable an automatic backup method:

# Click on that option.
# Click '''Deactivate'''.

Manage API Credentials

2023-09-19T13:48:10Z

Lawrence:

In WHMCS 7.2 and later, you can generate unique API authentication credentials. This allows for better management and security for provisioning access to API connected devices and systems.

You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > API Credentials'''.

For more information about using the WHMCS API, see our [https://developers.whmcs.com/api/ API documentation].

== API Roles ==

<div class="docs-alert-danger">
<span class="title">Roles and Credentials</span><br />
You '''must''' create at least one API role before you can generate API credentials.
</div>

API authentication credentials can limit individual API actions. This enables greater control and security when connected apps and services use credentials to access your WHMCS. For more information about API credentials, see [https://developers.whmcs.com/api/authentication/#authenticating-with-api-credentials our developer documentation].

The API Roles you define provide a authorization subset of [https://developers.whmcs.com/api/ API actions]. API credentials are for one or more of these roles. When something makes an API request, if any role provides permission to the requested action, the system will authorize the request and allow it to complete.

=== Creating API Roles ===

To create an admin API role:

# Choose the '''API Roles''' tab.
# Click '''Create API Role'''.
# Enter a role name and description.
#* The description is optional.
#* You can change the role name and description at any point in the future.
# Use the left-side menu to find API permissions.
# Check the desired API permissions.
# Click '''Save'''.

=== Viewing and Editing Roles ===

You can view the API permissions for a role by clicking the arrow icon for that role in the list.

[[File:API_Role_show_detail.png|550px]]

To update the role name, description, or API permissions, click the '''Edit''' icon, make the desired updates, and click '''Save'''.

=== Deleting Roles ===

To delete a role, click the '''Trash''' icon and then click '''Delete'''.

When you delete a role, the system will unassign the targeted role from any API credentials. If you recreate the role in the future, the system will not automatically assign it to those affected API credentials again.

== API Credentials ==

You may create as many API credential pairs for an admin as you require. You may remove any credential pair to invalidate access and authentication attempts that are received with that identifier.

You can also [[Administrator Users|alter the admin's login password]] without invalidating API credentials. If you disable or remove entirely an admin user, any associated API credentials will become invalid.

If your copy of the secret is lost, create a new API credential pair. Then, use the newly-generated identifier and secret in your integration. Make certain to '''delete''' the previous credential pair.

=== Creating API Credentials ===

[[File:API_Cred_generate_select_admin2.png|right|thumb|250px]]

<div class="docs-alert-danger">
<span class="title">Roles and Credentials</span><br />
You '''must''' create at least one API role before you can generate API credentials.
</div>

To create new admin API authentication credentials:

# Choose the '''API Credentials''' tab.
# Click '''Generate New API Credential'''.
# Select the admin who the new credential will authenticate.
# Optionally, enter a description.
# Select the desired API roles (see above).
# Click '''Generate'''. The system will provision a unique API credential and the credential identifier and secret will display. Use these instead of the admin's username and password for API authentication.[[File:API_Cred_generated_pair2.png|550px]]<div class="docs-alert-warning">You must copy the Secret value at this time. If you lose this, you will need to generate a new credential pair.</div>
# Click '''Close'''.

The new API credential will appear in the list.

[[File:API_Cred_table2.png|550px]]

=== Viewing and Editing Credentials ===

You can update the description and associated API roles for a credential at any time.

<div class="docs-alert-warning">If you only want to edit the description, click that description in the list of credentials. Update the description and then click the checkmark icon.</div>

To do this:

# Click the '''Edit''' icon for the desired credential.
# Select the desired API roles.
# Click '''Save'''.

Associating one or more API roles to an API credential will determine the permitted actions when WHMCS receives an API request containing the credential's authorization details. Credentials without an assigned role will effectively have no authorization. If there are one or more assigned roles but none of the roles have any allowed API actions, the system will deny all requests for authorization.

===Removing Admin API Authentication Credentials===

You may revoke API authentication by removing a generated credential.

To remove a authentication with a given credential, find that credential in the list, click the '''Trash''' icon, and then click '''Delete'''.

==Compatibility Role On Update to v7.4==

API credentials that you generate in WHMCS v7.2 and v7.3 follow a simple authorization model. The system grants full authorization to any API request if the identifier and secret pass the authentication verification check. This is the same behavior that the system uses with an Admin username and password in all previous and current versions of WHMCS.

We removed this simple authorization model in WHMCS v7.4 for API Credentials and replaced it with a Role Based Access Control (RBAC) authorization model. This new model allows for both easy management and explicit authorization across all your API apps and service integrations.

The system performs a one-time forward compatibility routine in the background when updating to WHMCS v7.4. This routine will identify any previously-generated API credentials. If the system finds any credentials, the routine will perform two operations on your behalf:

* It will generate a compatibility role that has all currently-selected API actions (emulating the previous, simple authorization model).
* It will assign the compatibility role to any found credentials.

These operations ensure that all API credential authorizations continue to function without interruption. The compatibility role selects all API actions that are available in WHMCS v7.3. The system won't automatically maintain this compatibility role since its purpose is merely to prevent immediate disruption. You may modify or remove this role for your integrations.

<div class="docs-alert-warning">We recommend creating and assigning targeted API roles that individually, and collectively, limit authorization for integrations. The continued use of a role that provides unrestricted authorization may expose unnecessary security risks.</div>

System Environment Guide

2023-08-08T11:58:04Z

Lawrence: /* Required */

WHMCS is compatible with most web server environments. Installing WHMCS in your web environment is usually straight forward. As well, WHMCS is continually providing updates which can seamlessly support environment updates from the upstream providers. However, as new technologies emerge and your current system's environment has access to new updates, it's important that you are aware of how they might affect your WHMCS deployment. This guide is designed help you and your system administrator prepare and manage your environment.

<div class="toclimit-2">__TOC__</div>

== Overview ==
WHMCS is designed for a traditional LAMP (Linux, Apache, MySQL, PHP) environment. The minimum requirements and basic version compatibility related to those sub-systems are provided in our [[System Requirements]].

The development of WHMCS is such that alternative technologies may be viable, however they are not tested and assistance from our Support Team will be limited. For example, if you wish to use NGINX instead of Apache, it may be technically possible. However, our Support will have limited knowledge about how to properly configure NGINX or debug behaviors that are specific to NGINX.

If you require the use of something other than Linux, Apache, or MySQL please consult with your system administrator to evaluate the immediate possibilities for (in)compatibility and long-term viability so that your environment management strategy accommodates for your specific requirements.

== Operating System ==
WHMCS is designed to run in a standard Linux operating/file system. WHMCS relies on PHP for interaction with the file system. In some operating systems (such as Windows) or environments (such as jails or chroots) the file system may have restrictions or inherent behaviors which may be hard to detect or uncommon. When possible, WHMCS provides notices that indicates incompatibility. If you require a different operating/file system, please discuss with your system administrator. Our Support Team is available to provide limited assistance to your system administrator for your custom environment.

Also of note, WHMCS relies heavily on the Linux Cron sub-system to trigger background tasks and perform periodic automation tasks such as deferred provisioning, service synchronization, invoice generation, billing, and more. You may learn more at the [[Crons| crons documentation]].

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Please note, the command line PHP used to invoke the cron will need to meet the same requirements as the [[#PHP| PHP]] binary used by your web server. This includes ini settings and enabled extensions.</div>

== Web Server ==
WHMCS is designed to work with the Apache web server version 2.x. While there are no special Apache configurations required for WHMCS, there are some advantages available to you and your WHMCS deployment that you may wish to consider.

=== Extensions ===

;mod_rewrite
:The Apache mod_rewrite module allows Apache to inspect and modify URLs and redirects through the use of .htaccess files within your web server docroot. WHMCS can create and manage a .htaccess file, and thus generate and consume friendly URLs in various parts of the product. This feature is described in more detail at [[Friendly URLs]].

=== Handler ===
The web server is responsible for all web applications on the server, and thus the Unix permissions granted to the php process (php handler) that operate with your web application are important. Some PHP handlers will execute all php code on the system as the same Unix user (server wide handlers like CGI & mod_php) while other handlers execute the PHP process as a specific user based on domain name (per vhost handlers like suphp, mod_ruid2). Both options are viable for WHMCS. However, as a matter of security, you need to ensure that no other applications on the server, outside your control, executes as the same Unix user. Your system administrator should be able to configure the web server so that this minimum level of security is met, or more conservatively, that the WHMCS web application process is executed by a user that is wholly unique amongst any other application on the server (even those within your control).

=== Directives ===

WHMCS uses configuration directives to alter the web server configuration on a per-directory basis. As Apache is the recommended web server software platform to run WHMCS on, these directives are included via the following .htaccess files.

; ~/.htaccess
: This file contains the mod_rewrite directives responsible for sending routable paths through the index.php file. This in turn allows the internal routing system to function, and furnishes WHMCS with the ability to create consumer friendly URLs. More information can be found on the [[Friendly URLs]] documentation page.

; ~/vendor/.htaccess
: This file prevents access to the ~/vendor directory. This ensures that the web server is not serving file requests directly from this location, and that WHMCS is still capable of accessing the libraries it needs to function. More information can be found on the [[Further_Security_Steps#Vendor_Directory|Further Security Steps]] documentation page.

While other web server technologies are not officially supported, we understand that some users do wish to run WHMCS in environments other than Apache. For those that do, you must ensure that the functionality offered by the aforementioned directives has been implemented by your web server configuration.

How this is achieved depends on the web server itself. If uncertain, then you should consult with your server administrator. As an example, you can find a guide detailing how to secure the vendor directory on the NGINX web server on the [[Nginx Directory Access Restriction]] documentation page.

== Database ==
WHMCS is designed to work with the MySQL database. Binary compatible alternatives (such as MariaDB) should be suitable, however their default configurations and optimizations are likely to be different and you should consult with your system administrator or database administrator.

=== Version Compatibility ===
{{:MySQL Version Support Matrix}}

=== Database Privileges ===
When installing or updating WHMCS, or when activating or deactivating modules, the following privileges are required:
* ALTER
* CREATE
* DROP
* INDEX

For day to day use, only the following database privileges are required. All others may be disabled.
* DELETE
* INSERT
* SELECT
* UPDATE
* LOCK TABLES

If you choose to restrict the privileges for day to day use, don't forget to grant the former privileges so database schema changes and optimizations can be performed by the update process.

=== Database Interaction ===
WHMCS internals utilize the PDO database API. If the PHP environment is v5.6, both a PDO based connection and a MySQL handle will be used for compatibility with legacy code.

If you are developing code for the WHMCS platform, it is recommended that you interact with the database via the [https://developers.whmcs.com/api/internal-api/ Local API], [https://developers.whmcs.com/advanced/db-interaction/ DBAL & ORM], or [[Using Models|Models]]. All three methods will abstract database connection details and system compatibility for you and will be supported by WHMCS for the foreseeable future. The [https://docs.whmcs.com/SQL_Helper_Functions?redirect=no SQL Helper Functions] are still present, although deprecated. Due to their ubiquitous usage, we anticipate supporting them as long as possible but recommend that you use one of the other methods above. You can learn more at [https://developers.whmcs.com/advanced/db-interaction/ Interacting with the Database] on our developer's site.

=== Encrypted Database Connections ===

<div class="docs-alert-info"> We added this support in WHMCS 8.8.</div>

Support for encrypted MySQL connections requires adding configuration variables to the <tt>configuration.php</tt> file. You can use the following variables:

* <tt>db_tls_ca</tt> — The path to the CA .pem file (for example, <tt>/var/www/html/whmcs/ca.pem</tt>).
* <tt>db_tls_ca_path</tt> — The path to the directory that contains the CA certificate files.
* <tt>db_tls_cert</tt> — The path to the client's certificate.
* <tt>db_tls_cipher</tt> — A list of one or more ciphers to use for SSL encryption, in an OpenSSL-compatible format.
* <tt>db_tls_key</tt> — The path to the client's key.
* <tt>db_tls_verify_cert</tt> — Disable (<tt>0</tt>) or enable (<tt>1</tt>) the server certificate.

You can add these variables before, during, or after installation using the [[Install On The Command Line|command-line installation method]] or after installation using the [[Installing WHMCS|browser-based installation method]]. For steps, see [https://help.whmcs.com/m/installation/l/1706785-enabling-encrypted-mysql-connections Enabling Encrypted MySQL Connections].

<div id="PHP_Version"> </div>

== PHP ==
WHMCS is written in PHP. Your environment's PHP will need to be a version supported by the version of WHMCS you are using. In general, this will be one of the PHP versions that is either under active development or is receiving security fixes from the upstream PHP maintainers.

Whenever possible, it is usually preferable to utilize a version of PHP that is under active development. Unfortunately, there can be a number of circumstances that may complicate the viability of using the latest stable release of PHP. These can range from a lack of control panel build support to incompatibility for other web applications on your server to backwards breaking behavior in PHP that inhibit ionCube Loader® support. Regardless, WHMCS always provides support for a security-monitored PHP version available from the PHP maintainers and we are continually prioritizing compatibility with their releases.

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Our [[PHP Upgrade Guide]] outlines the essential steps you can follow in preparation for a PHP upgrade. In WHMCS 7.5 we also provide the [[PHP_Version_Compatibility_Assessment| PHP Version Compatibility Assessment Utility]] designed to scan your WHMCS for any encoded files that may not be compatible for your desired PHP version.</div>

=== Version Compatibility ===
{{:PHP Version Support Matrix}}

=== Extensions ===

WHMCS requires most of the default compiled extensions (for example, PDO, mysqlnd, JSON, libxml, DOM, or Fileinfo). We assume that you will not intentionally disable them in the environment.

You must also compile and enable the following additional extensions:

==== Required ====
; cURL with SSL Support
: cURL is used when interacting with APIs of external systems such as the WHMCS Licensing & Update servers, payment gateways, servers that host your products, etc. cURL's SSL support must be enabled so that verified and encrypted communication is possible.
<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>WHMCS will check for Curl version 7.36 or above.</div>
; GD2
: GD2 Image Library is used when performing graphic manipulation, such as image thumbnails and PDFs.
; IMAP**
: **IMAP is only required if you are utilizing support departments which access mailboxes.
; ionCube Loader
: See the [[#ionCube| ionCube Loader]] section below for more detail.
; JSON
: JSON exchanges data in the UI (for example, displaying success messages after completing an action like changing a password on a service).
; MYSQL**
: ** The original MySQL extension is required if, and only if, your environment uses PHP v5.6.
; PDO_MYSQL
: While the basic PDO API extension is compiled by default in PHP, you must also have the PDO MySQL driver enabled so that PDO can communicate with your MySQL database server.
;Reflection
: Reflection adds the ability to examine and identify classes, interfaces, functions, methods, and extensions within your application. As part of this, the extension can check also for and retrieve documented comments within the same classes, interfaces, functions, and methods.
; SOAP**
: **SOAP is only required by some specific, but possibly important, modules. It is used when interacting with their corresponding external services, such as EU VAT, OpenSRS, eWay Tokens, etc.
; XML
: WHMCS uses the SimpleXML extension that PHP compiles by default. It is highly used for communication with remote systems, such as registrars, payment gateways, and servers.

==== Recommended ====
; BC Math
: The functions provided by BC Math are used when available. They provide performance improvements for when generating cryptographic data.
; Fileinfo
: The functions provided by Fileinfo are used when available. They provide functionalities to aid in determining the content type and encoding of uploaded files.
; GMP
: The functions provided by GMP are used when available. They provide significant performance improvements for when generating cryptographic data.
; iconv
: The iconv extension is for character set conversion, i.e. managing different non-latin characters. If available, this extension provides significant performance improvements and is highly recommended.
; Intl
: Intl performs character inspection and transformation, such as in IDN to perform Punycode conversions and transliterations. While we provide a third party dependency to compensate for the absence of Intl, it is much more performant to have the actual extension in the environment.
; mbstring
: The mbstring extension is for multi-byte character support, i.e managing non-Latin characters and glyphs. If available, this extension provides significant performance, allows for broader support of characters and glyphs common throughout digital communications, and is highly recommended.
; OpenSSL
: OpenSSL is for secure communications and random number generation. If available, this extension will be used and provide significant performance improvements for cryptographic routines.

=== PHP INI Settings ===
; allow_url_fopen
: allow_url_fopen must be enabled for the WHMCS Updater.

<div id="IonCube_Version"> </div>

== ionCube ==

ionCube is a set of encoding and decoding tools that provide obfuscation and performance for PHP software. The decoder tool is a "loader" in the server environment. The encoder tool, an "encoder," is part of PHP developers' publication processes.

WHMCS is encoded with ionCube and requires that you install and enable the ionCube Loader extension in your server environment. We recommend running the latest version of the ionCube Loader for your PHP version. Our [[ioncube Installation Tutorial|ionCube Installation Tutorial]] provides an overview for installing this extension in your environment.

Usually, ionCube will publish a complementing loader several weeks following a new PHP version.

Using this latest loader will afford you two benefits:
* You have the potential for running previously-encoded files using a new base PHP version and running unencoded (raw) PHP code that is compatible with the base PHP version.
* You can run newly-encoded files from a new ionCube Encoder (if one was published).

The ionCube Encoder requires the developer to itemize the PHP versions to support. This helps to mitigate the limitations for supporting certain PHP versions concurrently: it is common for PHP applications to not support the latest PHP version on the initial PHP release date. Applications may also have further requirements about the oldest supported PHP version and the required loader.

Each WHMCS version has always supported at least two PHP versions. Each new version of WHMCS has always supported at least one of the PHP versions supported in the previous WHMCS publication. This perpetual overlap of PHP version support across WHMCS publications means that you always have a path to upgrade your PHP environment without having to update the WHMCS software at the same time. As well, it allows the WHMCS Updater to safely automate updates for your current environment. Providing this overlap is integral to enabling your environment maintenance strategy, giving you the best balance of security, stability and forward compatibility as soon as possible.

=== Version Compatibility ===
{{:IonCube Loader Version Matrix}}

System Environment Guide

2023-08-08T11:55:37Z

Lawrence: /* Recommended */

WHMCS is compatible with most web server environments. Installing WHMCS in your web environment is usually straight forward. As well, WHMCS is continually providing updates which can seamlessly support environment updates from the upstream providers. However, as new technologies emerge and your current system's environment has access to new updates, it's important that you are aware of how they might affect your WHMCS deployment. This guide is designed help you and your system administrator prepare and manage your environment.

<div class="toclimit-2">__TOC__</div>

== Overview ==
WHMCS is designed for a traditional LAMP (Linux, Apache, MySQL, PHP) environment. The minimum requirements and basic version compatibility related to those sub-systems are provided in our [[System Requirements]].

The development of WHMCS is such that alternative technologies may be viable, however they are not tested and assistance from our Support Team will be limited. For example, if you wish to use NGINX instead of Apache, it may be technically possible. However, our Support will have limited knowledge about how to properly configure NGINX or debug behaviors that are specific to NGINX.

If you require the use of something other than Linux, Apache, or MySQL please consult with your system administrator to evaluate the immediate possibilities for (in)compatibility and long-term viability so that your environment management strategy accommodates for your specific requirements.

== Operating System ==
WHMCS is designed to run in a standard Linux operating/file system. WHMCS relies on PHP for interaction with the file system. In some operating systems (such as Windows) or environments (such as jails or chroots) the file system may have restrictions or inherent behaviors which may be hard to detect or uncommon. When possible, WHMCS provides notices that indicates incompatibility. If you require a different operating/file system, please discuss with your system administrator. Our Support Team is available to provide limited assistance to your system administrator for your custom environment.

Also of note, WHMCS relies heavily on the Linux Cron sub-system to trigger background tasks and perform periodic automation tasks such as deferred provisioning, service synchronization, invoice generation, billing, and more. You may learn more at the [[Crons| crons documentation]].

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Please note, the command line PHP used to invoke the cron will need to meet the same requirements as the [[#PHP| PHP]] binary used by your web server. This includes ini settings and enabled extensions.</div>

== Web Server ==
WHMCS is designed to work with the Apache web server version 2.x. While there are no special Apache configurations required for WHMCS, there are some advantages available to you and your WHMCS deployment that you may wish to consider.

=== Extensions ===

;mod_rewrite
:The Apache mod_rewrite module allows Apache to inspect and modify URLs and redirects through the use of .htaccess files within your web server docroot. WHMCS can create and manage a .htaccess file, and thus generate and consume friendly URLs in various parts of the product. This feature is described in more detail at [[Friendly URLs]].

=== Handler ===
The web server is responsible for all web applications on the server, and thus the Unix permissions granted to the php process (php handler) that operate with your web application are important. Some PHP handlers will execute all php code on the system as the same Unix user (server wide handlers like CGI & mod_php) while other handlers execute the PHP process as a specific user based on domain name (per vhost handlers like suphp, mod_ruid2). Both options are viable for WHMCS. However, as a matter of security, you need to ensure that no other applications on the server, outside your control, executes as the same Unix user. Your system administrator should be able to configure the web server so that this minimum level of security is met, or more conservatively, that the WHMCS web application process is executed by a user that is wholly unique amongst any other application on the server (even those within your control).

=== Directives ===

WHMCS uses configuration directives to alter the web server configuration on a per-directory basis. As Apache is the recommended web server software platform to run WHMCS on, these directives are included via the following .htaccess files.

; ~/.htaccess
: This file contains the mod_rewrite directives responsible for sending routable paths through the index.php file. This in turn allows the internal routing system to function, and furnishes WHMCS with the ability to create consumer friendly URLs. More information can be found on the [[Friendly URLs]] documentation page.

; ~/vendor/.htaccess
: This file prevents access to the ~/vendor directory. This ensures that the web server is not serving file requests directly from this location, and that WHMCS is still capable of accessing the libraries it needs to function. More information can be found on the [[Further_Security_Steps#Vendor_Directory|Further Security Steps]] documentation page.

While other web server technologies are not officially supported, we understand that some users do wish to run WHMCS in environments other than Apache. For those that do, you must ensure that the functionality offered by the aforementioned directives has been implemented by your web server configuration.

How this is achieved depends on the web server itself. If uncertain, then you should consult with your server administrator. As an example, you can find a guide detailing how to secure the vendor directory on the NGINX web server on the [[Nginx Directory Access Restriction]] documentation page.

== Database ==
WHMCS is designed to work with the MySQL database. Binary compatible alternatives (such as MariaDB) should be suitable, however their default configurations and optimizations are likely to be different and you should consult with your system administrator or database administrator.

=== Version Compatibility ===
{{:MySQL Version Support Matrix}}

=== Database Privileges ===
When installing or updating WHMCS, or when activating or deactivating modules, the following privileges are required:
* ALTER
* CREATE
* DROP
* INDEX

For day to day use, only the following database privileges are required. All others may be disabled.
* DELETE
* INSERT
* SELECT
* UPDATE
* LOCK TABLES

If you choose to restrict the privileges for day to day use, don't forget to grant the former privileges so database schema changes and optimizations can be performed by the update process.

=== Database Interaction ===
WHMCS internals utilize the PDO database API. If the PHP environment is v5.6, both a PDO based connection and a MySQL handle will be used for compatibility with legacy code.

If you are developing code for the WHMCS platform, it is recommended that you interact with the database via the [https://developers.whmcs.com/api/internal-api/ Local API], [https://developers.whmcs.com/advanced/db-interaction/ DBAL & ORM], or [[Using Models|Models]]. All three methods will abstract database connection details and system compatibility for you and will be supported by WHMCS for the foreseeable future. The [https://docs.whmcs.com/SQL_Helper_Functions?redirect=no SQL Helper Functions] are still present, although deprecated. Due to their ubiquitous usage, we anticipate supporting them as long as possible but recommend that you use one of the other methods above. You can learn more at [https://developers.whmcs.com/advanced/db-interaction/ Interacting with the Database] on our developer's site.

=== Encrypted Database Connections ===

<div class="docs-alert-info"> We added this support in WHMCS 8.8.</div>

Support for encrypted MySQL connections requires adding configuration variables to the <tt>configuration.php</tt> file. You can use the following variables:

* <tt>db_tls_ca</tt> — The path to the CA .pem file (for example, <tt>/var/www/html/whmcs/ca.pem</tt>).
* <tt>db_tls_ca_path</tt> — The path to the directory that contains the CA certificate files.
* <tt>db_tls_cert</tt> — The path to the client's certificate.
* <tt>db_tls_cipher</tt> — A list of one or more ciphers to use for SSL encryption, in an OpenSSL-compatible format.
* <tt>db_tls_key</tt> — The path to the client's key.
* <tt>db_tls_verify_cert</tt> — Disable (<tt>0</tt>) or enable (<tt>1</tt>) the server certificate.

You can add these variables before, during, or after installation using the [[Install On The Command Line|command-line installation method]] or after installation using the [[Installing WHMCS|browser-based installation method]]. For steps, see [https://help.whmcs.com/m/installation/l/1706785-enabling-encrypted-mysql-connections Enabling Encrypted MySQL Connections].

<div id="PHP_Version"> </div>

== PHP ==
WHMCS is written in PHP. Your environment's PHP will need to be a version supported by the version of WHMCS you are using. In general, this will be one of the PHP versions that is either under active development or is receiving security fixes from the upstream PHP maintainers.

Whenever possible, it is usually preferable to utilize a version of PHP that is under active development. Unfortunately, there can be a number of circumstances that may complicate the viability of using the latest stable release of PHP. These can range from a lack of control panel build support to incompatibility for other web applications on your server to backwards breaking behavior in PHP that inhibit ionCube Loader® support. Regardless, WHMCS always provides support for a security-monitored PHP version available from the PHP maintainers and we are continually prioritizing compatibility with their releases.

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Our [[PHP Upgrade Guide]] outlines the essential steps you can follow in preparation for a PHP upgrade. In WHMCS 7.5 we also provide the [[PHP_Version_Compatibility_Assessment| PHP Version Compatibility Assessment Utility]] designed to scan your WHMCS for any encoded files that may not be compatible for your desired PHP version.</div>

=== Version Compatibility ===
{{:PHP Version Support Matrix}}

=== Extensions ===

WHMCS requires most of the default compiled extensions (for example, PDO, mysqlnd, JSON, libxml, DOM, or Fileinfo). We assume that you will not intentionally disable them in the environment.

You must also compile and enable the following additional extensions:

==== Required ====
; ionCube Loader
: See the [[#ionCube| ionCube Loader]] section below for more detail.
; PDO_MYSQL
: While the basic PDO API extension is compiled by default in PHP, you must also have the PDO MySQL driver enabled so that PDO can communicate with your MySQL database server.
; cURL with SSL Support
: cURL is used when interacting with APIs of external systems such as the WHMCS Licensing & Update servers, payment gateways, servers that host your products, etc. cURL's SSL support must be enabled so that verified and encrypted communication is possible.
<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>WHMCS will check for Curl version 7.36 or above.</div>
; GD2
: GD2 Image Library is used when performing graphic manipulation, such as image thumbnails and PDFs.
;Reflection
: Reflection adds the ability to examine and identify classes, interfaces, functions, methods, and extensions within your application. As part of this, the extension can check also for and retrieve documented comments within the same classes, interfaces, functions, and methods.
; XML
: WHMCS uses the SimpleXML extension that PHP compiles by default. It is highly used for communication with remote systems, such as registrars, payment gateways, and servers.
; JSON
: JSON exchanges data in the UI (for example, displaying success messages after completing an action like changing a password on a service).
; SOAP**
: **SOAP is only required by some specific, but possibly important, modules. It is used when interacting with their corresponding external services, such as EU VAT, OpenSRS, eWay Tokens, etc.
; IMAP**
: **IMAP is only required if you are utilizing support departments which access mailboxes.
; MYSQL**
: ** The original MySQL extension is required if, and only if, your environment uses PHP v5.6.

==== Recommended ====
; BC Math
: The functions provided by BC Math are used when available. They provide performance improvements for when generating cryptographic data.
; Fileinfo
: The functions provided by Fileinfo are used when available. They provide functionalities to aid in determining the content type and encoding of uploaded files.
; GMP
: The functions provided by GMP are used when available. They provide significant performance improvements for when generating cryptographic data.
; iconv
: The iconv extension is for character set conversion, i.e. managing different non-latin characters. If available, this extension provides significant performance improvements and is highly recommended.
; Intl
: Intl performs character inspection and transformation, such as in IDN to perform Punycode conversions and transliterations. While we provide a third party dependency to compensate for the absence of Intl, it is much more performant to have the actual extension in the environment.
; mbstring
: The mbstring extension is for multi-byte character support, i.e managing non-Latin characters and glyphs. If available, this extension provides significant performance, allows for broader support of characters and glyphs common throughout digital communications, and is highly recommended.
; OpenSSL
: OpenSSL is for secure communications and random number generation. If available, this extension will be used and provide significant performance improvements for cryptographic routines.

=== PHP INI Settings ===
; allow_url_fopen
: allow_url_fopen must be enabled for the WHMCS Updater.

<div id="IonCube_Version"> </div>

== ionCube ==

ionCube is a set of encoding and decoding tools that provide obfuscation and performance for PHP software. The decoder tool is a "loader" in the server environment. The encoder tool, an "encoder," is part of PHP developers' publication processes.

WHMCS is encoded with ionCube and requires that you install and enable the ionCube Loader extension in your server environment. We recommend running the latest version of the ionCube Loader for your PHP version. Our [[ioncube Installation Tutorial|ionCube Installation Tutorial]] provides an overview for installing this extension in your environment.

Usually, ionCube will publish a complementing loader several weeks following a new PHP version.

Using this latest loader will afford you two benefits:
* You have the potential for running previously-encoded files using a new base PHP version and running unencoded (raw) PHP code that is compatible with the base PHP version.
* You can run newly-encoded files from a new ionCube Encoder (if one was published).

The ionCube Encoder requires the developer to itemize the PHP versions to support. This helps to mitigate the limitations for supporting certain PHP versions concurrently: it is common for PHP applications to not support the latest PHP version on the initial PHP release date. Applications may also have further requirements about the oldest supported PHP version and the required loader.

Each WHMCS version has always supported at least two PHP versions. Each new version of WHMCS has always supported at least one of the PHP versions supported in the previous WHMCS publication. This perpetual overlap of PHP version support across WHMCS publications means that you always have a path to upgrade your PHP environment without having to update the WHMCS software at the same time. As well, it allows the WHMCS Updater to safely automate updates for your current environment. Providing this overlap is integral to enabling your environment maintenance strategy, giving you the best balance of security, stability and forward compatibility as soon as possible.

=== Version Compatibility ===
{{:IonCube Loader Version Matrix}}

System Environment Guide

2023-06-07T14:53:56Z

Lawrence: /* Recommended */

WHMCS is compatible with most web server environments. Installing WHMCS in your web environment is usually straight forward. As well, WHMCS is continually providing updates which can seamlessly support environment updates from the upstream providers. However, as new technologies emerge and your current system's environment has access to new updates, it's important that you are aware of how they might affect your WHMCS deployment. This guide is designed help you and your system administrator prepare and manage your environment.

<div class="toclimit-2">__TOC__</div>

== Overview ==
WHMCS is designed for a traditional LAMP (Linux, Apache, MySQL, PHP) environment. The minimum requirements and basic version compatibility related to those sub-systems are provided in our [[System Requirements]].

The development of WHMCS is such that alternative technologies may be viable, however they are not tested and assistance from our Support Team will be limited. For example, if you wish to use NGINX instead of Apache, it may be technically possible. However, our Support will have limited knowledge about how to properly configure NGINX or debug behaviors that are specific to NGINX.

If you require the use of something other than Linux, Apache, or MySQL please consult with your system administrator to evaluate the immediate possibilities for (in)compatibility and long-term viability so that your environment management strategy accommodates for your specific requirements.

== Operating System ==
WHMCS is designed to run in a standard Linux operating/file system. WHMCS relies on PHP for interaction with the file system. In some operating systems (such as Windows) or environments (such as jails or chroots) the file system may have restrictions or inherent behaviors which may be hard to detect or uncommon. When possible, WHMCS provides notices that indicates incompatibility. If you require a different operating/file system, please discuss with your system administrator. Our Support Team is available to provide limited assistance to your system administrator for your custom environment.

Also of note, WHMCS relies heavily on the Linux Cron sub-system to trigger background tasks and perform periodic automation tasks such as deferred provisioning, service synchronization, invoice generation, billing, and more. You may learn more at the [[Crons| crons documentation]].

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Please note, the command line PHP used to invoke the cron will need to meet the same requirements as the [[#PHP| PHP]] binary used by your web server. This includes ini settings and enabled extensions.</div>

== Web Server ==
WHMCS is designed to work with the Apache web server version 2.x. While there are no special Apache configurations required for WHMCS, there are some advantages available to you and your WHMCS deployment that you may wish to consider.

=== Extensions ===

;mod_rewrite
:The Apache mod_rewrite module allows Apache to inspect and modify URLs and redirects through the use of .htaccess files within your web server docroot. WHMCS can create and manage a .htaccess file, and thus generate and consume friendly URLs in various parts of the product. This feature is described in more detail at [[Friendly URLs]].

=== Handler ===
The web server is responsible for all web applications on the server, and thus the Unix permissions granted to the php process (php handler) that operate with your web application are important. Some PHP handlers will execute all php code on the system as the same Unix user (server wide handlers like CGI & mod_php) while other handlers execute the PHP process as a specific user based on domain name (per vhost handlers like suphp, mod_ruid2). Both options are viable for WHMCS. However, as a matter of security, you need to ensure that no other applications on the server, outside your control, executes as the same Unix user. Your system administrator should be able to configure the web server so that this minimum level of security is met, or more conservatively, that the WHMCS web application process is executed by a user that is wholly unique amongst any other application on the server (even those within your control).

=== Directives ===

WHMCS uses configuration directives to alter the web server configuration on a per-directory basis. As Apache is the recommended web server software platform to run WHMCS on, these directives are included via the following .htaccess files.

; ~/.htaccess
: This file contains the mod_rewrite directives responsible for sending routable paths through the index.php file. This in turn allows the internal routing system to function, and furnishes WHMCS with the ability to create consumer friendly URLs. More information can be found on the [[Friendly URLs]] documentation page.

; ~/vendor/.htaccess
: This file prevents access to the ~/vendor directory. This ensures that the web server is not serving file requests directly from this location, and that WHMCS is still capable of accessing the libraries it needs to function. More information can be found on the [[Further_Security_Steps#Vendor_Directory|Further Security Steps]] documentation page.

While other web server technologies are not officially supported, we understand that some users do wish to run WHMCS in environments other than Apache. For those that do, you must ensure that the functionality offered by the aforementioned directives has been implemented by your web server configuration.

How this is achieved depends on the web server itself. If uncertain, then you should consult with your server administrator. As an example, you can find a guide detailing how to secure the vendor directory on the NGINX web server on the [[Nginx Directory Access Restriction]] documentation page.

== Database ==
WHMCS is designed to work with the MySQL database. Binary compatible alternatives (such as MariaDB) should be suitable, however their default configurations and optimizations are likely to be different and you should consult with your system administrator or database administrator.

=== Version Compatibility ===
{{:MySQL Version Support Matrix}}

=== Database Privileges ===
When installing or updating WHMCS, or when activating or deactivating modules, the following privileges are required:
* ALTER
* CREATE
* DROP
* INDEX

For day to day use, only the following database privileges are required. All others may be disabled.
* DELETE
* INSERT
* SELECT
* UPDATE
* LOCK TABLES

If you choose to restrict the privileges for day to day use, don't forget to grant the former privileges so database schema changes and optimizations can be performed by the update process.

=== Database Interaction ===
WHMCS internals utilize the PDO database API. If the PHP environment is v5.6, both a PDO based connection and a MySQL handle will be used for compatibility with legacy code.

If you are developing code for the WHMCS platform, it is recommended that you interact with the database via the [https://developers.whmcs.com/api/internal-api/ Local API], [https://developers.whmcs.com/advanced/db-interaction/ DBAL & ORM], or [[Using Models|Models]]. All three methods will abstract database connection details and system compatibility for you and will be supported by WHMCS for the foreseeable future. The [https://docs.whmcs.com/SQL_Helper_Functions?redirect=no SQL Helper Functions] are still present, although deprecated. Due to their ubiquitous usage, we anticipate supporting them as long as possible but recommend that you use one of the other methods above. You can learn more at [https://developers.whmcs.com/advanced/db-interaction/ Interacting with the Database] on our developer's site.
<div id="PHP_Version"> </div>
== PHP ==
WHMCS is written in PHP. Your environment's PHP will need to be a version supported by the version of WHMCS you are using. In general, this will be one of the PHP versions that is either under active development or is receiving security fixes from the upstream PHP maintainers.

Whenever possible, it is usually preferable to utilize a version of PHP that is under active development. Unfortunately, there can be a number of circumstances that may complicate the viability of using the latest stable release of PHP. These can range from a lack of control panel build support to incompatibility for other web applications on your server to backwards breaking behavior in PHP that inhibit ionCube Loader® support. Regardless, WHMCS always provides support for a security-monitored PHP version available from the PHP maintainers and we are continually prioritizing compatibility with their releases.

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Our [[PHP Upgrade Guide]] outlines the essential steps you can follow in preparation for a PHP upgrade. In WHMCS 7.5 we also provide the [[PHP_Version_Compatibility_Assessment| PHP Version Compatibility Assessment Utility]] designed to scan your WHMCS for any encoded files that may not be compatible for your desired PHP version.</div>

=== Version Compatibility ===
{{:PHP Version Support Matrix}}

=== Extensions ===

WHMCS requires most of the default compiled extensions (for example, PDO, mysqlnd, JSON, libxml, DOM, or Fileinfo). We assume that you will not intentionally disable them in the environment.

You must also compile and enable the following additional extensions:

==== Required ====
; ionCube Loader
: See the [[#ionCube| ionCube Loader]] section below for more detail.
; PDO_MYSQL
: While the basic PDO API extension is compiled by default in PHP, you must also have the PDO MySQL driver enabled so that PDO can communicate with your MySQL database server.
; cURL with SSL Support
: cURL is used when interacting with APIs of external systems such as the WHMCS Licensing & Update servers, payment gateways, servers that host your products, etc. cURL's SSL support must be enabled so that verified and encrypted communication is possible.
<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>WHMCS will check for Curl version 7.36 or above.</div>
; GD2
: GD2 Image Library is used when performing graphic manipulation, such as image thumbnails and PDFs.
; XML
: WHMCS uses the SimpleXML extension that PHP compiles by default. It is highly used for communication with remote systems, such as registrars, payment gateways, and servers.
; JSON
: JSON exchanges data in the UI (for example, displaying success messages after completing an action like changing a password on a service).
; SOAP**
: **SOAP is only required by some specific, but possibly important, modules. It is used when interacting with their corresponding external services, such as EU VAT, OpenSRS, eWay Tokens, etc.
; IMAP**
: **IMAP is only required if you are utilizing support departments which access mailboxes.
; MYSQL**
: ** The original MySQL extension is required if, and only if, your environment uses PHP v5.6.

==== Recommended ====
; Intl
: Intl performs character inspection and transformation, such as in IDN to perform Punycode conversions and transliterations. While we provide a third party dependency to compensate for the absence of Intl, it is much more performant to have the actual extension in the environment.
; iconv
: The iconv extension is for character set conversion, i.e. managing different non-latin characters. If available, this extension provides significant performance improvements and is highly recommended.
; mbstring
: The mbstring extension is for multi-byte character support, i.e managing non-Latin characters and glyphs. If available, this extension provides significant performance, allows for broader support of characters and glyphs common throughout digital communications, and is highly recommended.
; OpenSSL
: OpenSSL is for secure communications and random number generation. If available, this extension will be used and provide significant performance improvements for cryptographic routines.
; GMP
: The functions provided by GMP are used when available. They provide significant performance improvements for when generating cryptographic data.
; BC Math
: The functions provided by BC Math are used when available. They provide performance improvements for when generating cryptographic data.
; Fileinfo
: The functions provided by Fileinfo are used when available. They provide functionalities to aid in determining the content type and encoding of uploaded files.

=== PHP INI Settings ===
; allow_url_fopen
: allow_url_fopen must be enabled for the WHMCS Updater.

<div id="IonCube_Version"> </div>

== ionCube ==

ionCube is a set of encoding and decoding tools that provide obfuscation and performance for PHP software. The decoder tool is a "loader" in the server environment. The encoder tool, an "encoder," is part of PHP developers' publication processes.

WHMCS is encoded with ionCube and requires that you install and enable the ionCube Loader extension in your server environment. We recommend running the latest version of the ionCube Loader for your PHP version. Our [[ioncube Installation Tutorial|ionCube Installation Tutorial]] provides an overview for installing this extension in your environment.

Usually, ionCube will publish a complementing loader several weeks following a new PHP version.

Using this latest loader will afford you two benefits:
* You have the potential for running previously-encoded files using a new base PHP version and running unencoded (raw) PHP code that is compatible with the base PHP version.
* You can run newly-encoded files from a new ionCube Encoder (if one was published).

The ionCube Encoder requires the developer to itemize the PHP versions to support. This helps to mitigate the limitations for supporting certain PHP versions concurrently: it is common for PHP applications to not support the latest PHP version on the initial PHP release date. Applications may also have further requirements about the oldest supported PHP version and the required loader.

Each WHMCS version has always supported at least two PHP versions. Each new version of WHMCS has always supported at least one of the PHP versions supported in the previous WHMCS publication. This perpetual overlap of PHP version support across WHMCS publications means that you always have a path to upgrade your PHP environment without having to update the WHMCS software at the same time. As well, it allows the WHMCS Updater to safely automate updates for your current environment. Providing this overlap is integral to enabling your environment maintenance strategy, giving you the best balance of security, stability and forward compatibility as soon as possible.

=== Version Compatibility ===
{{:IonCube Loader Version Matrix}}

System Environment Guide

2023-06-07T14:53:31Z

Lawrence: /* Required */

WHMCS is compatible with most web server environments. Installing WHMCS in your web environment is usually straight forward. As well, WHMCS is continually providing updates which can seamlessly support environment updates from the upstream providers. However, as new technologies emerge and your current system's environment has access to new updates, it's important that you are aware of how they might affect your WHMCS deployment. This guide is designed help you and your system administrator prepare and manage your environment.

<div class="toclimit-2">__TOC__</div>

== Overview ==
WHMCS is designed for a traditional LAMP (Linux, Apache, MySQL, PHP) environment. The minimum requirements and basic version compatibility related to those sub-systems are provided in our [[System Requirements]].

The development of WHMCS is such that alternative technologies may be viable, however they are not tested and assistance from our Support Team will be limited. For example, if you wish to use NGINX instead of Apache, it may be technically possible. However, our Support will have limited knowledge about how to properly configure NGINX or debug behaviors that are specific to NGINX.

If you require the use of something other than Linux, Apache, or MySQL please consult with your system administrator to evaluate the immediate possibilities for (in)compatibility and long-term viability so that your environment management strategy accommodates for your specific requirements.

== Operating System ==
WHMCS is designed to run in a standard Linux operating/file system. WHMCS relies on PHP for interaction with the file system. In some operating systems (such as Windows) or environments (such as jails or chroots) the file system may have restrictions or inherent behaviors which may be hard to detect or uncommon. When possible, WHMCS provides notices that indicates incompatibility. If you require a different operating/file system, please discuss with your system administrator. Our Support Team is available to provide limited assistance to your system administrator for your custom environment.

Also of note, WHMCS relies heavily on the Linux Cron sub-system to trigger background tasks and perform periodic automation tasks such as deferred provisioning, service synchronization, invoice generation, billing, and more. You may learn more at the [[Crons| crons documentation]].

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Please note, the command line PHP used to invoke the cron will need to meet the same requirements as the [[#PHP| PHP]] binary used by your web server. This includes ini settings and enabled extensions.</div>

== Web Server ==
WHMCS is designed to work with the Apache web server version 2.x. While there are no special Apache configurations required for WHMCS, there are some advantages available to you and your WHMCS deployment that you may wish to consider.

=== Extensions ===

;mod_rewrite
:The Apache mod_rewrite module allows Apache to inspect and modify URLs and redirects through the use of .htaccess files within your web server docroot. WHMCS can create and manage a .htaccess file, and thus generate and consume friendly URLs in various parts of the product. This feature is described in more detail at [[Friendly URLs]].

=== Handler ===
The web server is responsible for all web applications on the server, and thus the Unix permissions granted to the php process (php handler) that operate with your web application are important. Some PHP handlers will execute all php code on the system as the same Unix user (server wide handlers like CGI & mod_php) while other handlers execute the PHP process as a specific user based on domain name (per vhost handlers like suphp, mod_ruid2). Both options are viable for WHMCS. However, as a matter of security, you need to ensure that no other applications on the server, outside your control, executes as the same Unix user. Your system administrator should be able to configure the web server so that this minimum level of security is met, or more conservatively, that the WHMCS web application process is executed by a user that is wholly unique amongst any other application on the server (even those within your control).

=== Directives ===

WHMCS uses configuration directives to alter the web server configuration on a per-directory basis. As Apache is the recommended web server software platform to run WHMCS on, these directives are included via the following .htaccess files.

; ~/.htaccess
: This file contains the mod_rewrite directives responsible for sending routable paths through the index.php file. This in turn allows the internal routing system to function, and furnishes WHMCS with the ability to create consumer friendly URLs. More information can be found on the [[Friendly URLs]] documentation page.

; ~/vendor/.htaccess
: This file prevents access to the ~/vendor directory. This ensures that the web server is not serving file requests directly from this location, and that WHMCS is still capable of accessing the libraries it needs to function. More information can be found on the [[Further_Security_Steps#Vendor_Directory|Further Security Steps]] documentation page.

While other web server technologies are not officially supported, we understand that some users do wish to run WHMCS in environments other than Apache. For those that do, you must ensure that the functionality offered by the aforementioned directives has been implemented by your web server configuration.

How this is achieved depends on the web server itself. If uncertain, then you should consult with your server administrator. As an example, you can find a guide detailing how to secure the vendor directory on the NGINX web server on the [[Nginx Directory Access Restriction]] documentation page.

== Database ==
WHMCS is designed to work with the MySQL database. Binary compatible alternatives (such as MariaDB) should be suitable, however their default configurations and optimizations are likely to be different and you should consult with your system administrator or database administrator.

=== Version Compatibility ===
{{:MySQL Version Support Matrix}}

=== Database Privileges ===
When installing or updating WHMCS, or when activating or deactivating modules, the following privileges are required:
* ALTER
* CREATE
* DROP
* INDEX

For day to day use, only the following database privileges are required. All others may be disabled.
* DELETE
* INSERT
* SELECT
* UPDATE
* LOCK TABLES

If you choose to restrict the privileges for day to day use, don't forget to grant the former privileges so database schema changes and optimizations can be performed by the update process.

=== Database Interaction ===
WHMCS internals utilize the PDO database API. If the PHP environment is v5.6, both a PDO based connection and a MySQL handle will be used for compatibility with legacy code.

If you are developing code for the WHMCS platform, it is recommended that you interact with the database via the [https://developers.whmcs.com/api/internal-api/ Local API], [https://developers.whmcs.com/advanced/db-interaction/ DBAL & ORM], or [[Using Models|Models]]. All three methods will abstract database connection details and system compatibility for you and will be supported by WHMCS for the foreseeable future. The [https://docs.whmcs.com/SQL_Helper_Functions?redirect=no SQL Helper Functions] are still present, although deprecated. Due to their ubiquitous usage, we anticipate supporting them as long as possible but recommend that you use one of the other methods above. You can learn more at [https://developers.whmcs.com/advanced/db-interaction/ Interacting with the Database] on our developer's site.
<div id="PHP_Version"> </div>
== PHP ==
WHMCS is written in PHP. Your environment's PHP will need to be a version supported by the version of WHMCS you are using. In general, this will be one of the PHP versions that is either under active development or is receiving security fixes from the upstream PHP maintainers.

Whenever possible, it is usually preferable to utilize a version of PHP that is under active development. Unfortunately, there can be a number of circumstances that may complicate the viability of using the latest stable release of PHP. These can range from a lack of control panel build support to incompatibility for other web applications on your server to backwards breaking behavior in PHP that inhibit ionCube Loader® support. Regardless, WHMCS always provides support for a security-monitored PHP version available from the PHP maintainers and we are continually prioritizing compatibility with their releases.

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Our [[PHP Upgrade Guide]] outlines the essential steps you can follow in preparation for a PHP upgrade. In WHMCS 7.5 we also provide the [[PHP_Version_Compatibility_Assessment| PHP Version Compatibility Assessment Utility]] designed to scan your WHMCS for any encoded files that may not be compatible for your desired PHP version.</div>

=== Version Compatibility ===
{{:PHP Version Support Matrix}}

=== Extensions ===

WHMCS requires most of the default compiled extensions (for example, PDO, mysqlnd, JSON, libxml, DOM, or Fileinfo). We assume that you will not intentionally disable them in the environment.

You must also compile and enable the following additional extensions:

==== Required ====
; ionCube Loader
: See the [[#ionCube| ionCube Loader]] section below for more detail.
; PDO_MYSQL
: While the basic PDO API extension is compiled by default in PHP, you must also have the PDO MySQL driver enabled so that PDO can communicate with your MySQL database server.
; cURL with SSL Support
: cURL is used when interacting with APIs of external systems such as the WHMCS Licensing & Update servers, payment gateways, servers that host your products, etc. cURL's SSL support must be enabled so that verified and encrypted communication is possible.
<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>WHMCS will check for Curl version 7.36 or above.</div>
; GD2
: GD2 Image Library is used when performing graphic manipulation, such as image thumbnails and PDFs.
; XML
: WHMCS uses the SimpleXML extension that PHP compiles by default. It is highly used for communication with remote systems, such as registrars, payment gateways, and servers.
; JSON
: JSON exchanges data in the UI (for example, displaying success messages after completing an action like changing a password on a service).
; SOAP**
: **SOAP is only required by some specific, but possibly important, modules. It is used when interacting with their corresponding external services, such as EU VAT, OpenSRS, eWay Tokens, etc.
; IMAP**
: **IMAP is only required if you are utilizing support departments which access mailboxes.
; MYSQL**
: ** The original MySQL extension is required if, and only if, your environment uses PHP v5.6.

==== Recommended ====
; iconv
: The iconv extension is for character set conversion, i.e. managing different non-latin characters. If available, this extension provides significant performance improvements and is highly recommended.
; mbstring
: The mbstring extension is for multi-byte character support, i.e managing non-Latin characters and glyphs. If available, this extension provides significant performance, allows for broader support of characters and glyphs common throughout digital communications, and is highly recommended.
; OpenSSL
: OpenSSL is for secure communications and random number generation. If available, this extension will be used and provide significant performance improvements for cryptographic routines.
; GMP
: The functions provided by GMP are used when available. They provide significant performance improvements for when generating cryptographic data.
; BC Math
: The functions provided by BC Math are used when available. They provide performance improvements for when generating cryptographic data.
; Fileinfo
: The functions provided by Fileinfo are used when available. They provide functionalities to aid in determining the content type and encoding of uploaded files.

=== PHP INI Settings ===
; allow_url_fopen
: allow_url_fopen must be enabled for the WHMCS Updater.

<div id="IonCube_Version"> </div>

== ionCube ==

ionCube is a set of encoding and decoding tools that provide obfuscation and performance for PHP software. The decoder tool is a "loader" in the server environment. The encoder tool, an "encoder," is part of PHP developers' publication processes.

WHMCS is encoded with ionCube and requires that you install and enable the ionCube Loader extension in your server environment. We recommend running the latest version of the ionCube Loader for your PHP version. Our [[ioncube Installation Tutorial|ionCube Installation Tutorial]] provides an overview for installing this extension in your environment.

Usually, ionCube will publish a complementing loader several weeks following a new PHP version.

Using this latest loader will afford you two benefits:
* You have the potential for running previously-encoded files using a new base PHP version and running unencoded (raw) PHP code that is compatible with the base PHP version.
* You can run newly-encoded files from a new ionCube Encoder (if one was published).

The ionCube Encoder requires the developer to itemize the PHP versions to support. This helps to mitigate the limitations for supporting certain PHP versions concurrently: it is common for PHP applications to not support the latest PHP version on the initial PHP release date. Applications may also have further requirements about the oldest supported PHP version and the required loader.

Each WHMCS version has always supported at least two PHP versions. Each new version of WHMCS has always supported at least one of the PHP versions supported in the previous WHMCS publication. This perpetual overlap of PHP version support across WHMCS publications means that you always have a path to upgrade your PHP environment without having to update the WHMCS software at the same time. As well, it allows the WHMCS Updater to safely automate updates for your current environment. Providing this overlap is integral to enabling your environment maintenance strategy, giving you the best balance of security, stability and forward compatibility as soon as possible.

=== Version Compatibility ===
{{:IonCube Loader Version Matrix}}

IWHMCS iPhone App

2023-05-19T15:02:16Z

Lawrence:

<div class="docs-alert-warning">
<span class="title">Acceptable Password Characters</span><br />
You cannot use the following characters in an administrator password:
& " ' < >
(ampersand, double quotes, single quotes, less than or greater than).
You can use other symbols without restrictions.
</div>
For more information, see [https://www.whmcs.com/mobile-apps/ the iWHMCS website].

==Setup Instructions==

1. To begin with (if you haven't already done so), you will need to order the iPhone addon from our client area. It's available as an addon to a license and can be ordered by logging into our client area at [http://www.whmcs.com/members/clientarea.php www.whmcs.com/members/clientarea.php] and selecting "View Available Addons" from the navigation bar.

2. Once you've ordered and paid, the addon will be instantly activated and you'll just need to perform a local key update by clicking '''Force License Update''' at '''Help > [[License Information]]''' inside your WHMCS installation to have it take effect.

3. Now, you're ready to download the iWHMCS app from the Apple iTunes App Store which you can do by [http://itunes.apple.com/gb/app/iwhmcs/id343647658?mt=8 finding iWHMCS in iTunes].

4. Once downloaded, sync your phone to install the app.

5. Now locate and open the app on your iphone's home screen

6. The first time you start it, you'll be asked to enter your authentication details. These consist of your WHMCS URL, admin username & password and an access key.

7. The WHMCS URL should be the URL to the frontend (client area), for example "http://demo.whmcs.com/" or "http://www.example.com/whmcs/" and the admin username & password the same as you use to login to the main admin area.

8. For the access key, you need to open up the configuration.php file for your WHMCS installation and add a line to it such as the one below:

<source lang="php">
$api_access_key = "abc123";
</source>

The '''abc123''' in the above should be replaced with a random series of letters and numbers created by you, and that same value is what you'll need to enter into the Access Key field of the iWHMCS configuration screen.

9. Then simply click Save and the connection will be tested. If any of the details were entered incorrectly you'll receive an Access Denied (username/password failure) or Invalid Access Key error message and be returned to re-enter the details.

10. If all was correct, you'll be taken straight to the homepage overview.

===Security PIN===
The app offers a security Personal Identification Number (PIN) feature. When a PIN has been configured you will be prompted to enter it when starting or returning to the aWHMCS app, so that even if your device is lost, stolen or being used by friends/family, they cannot access your business data. To configure the PIN:
[[File:android_pin.png|thumb|Edit Security PIN]]

*From the Home screen, tap the options icon,
*Tap Settings
*Tap PIN code
*Follow on on screen instructions to choose your 4 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 and the PIN protection will be removed.

==Common Problems==

===Invalid IP===
This error means the API Access Key has not been added successfully to the configuration.php file. Please refer to step 8 above. The $api_access_key line should go before the closing ?> tag.

===No Server Response/Invalid URL===
Seeing either the "No Server Response" or "Invalid URL" error suggests an empty or malformed response was received by the server. This is often caused by a blank space in user modifiable files. Please refer to [[Blank_Pages#Blank_Pages_Elsewhere]] for steps to resolve this error.

===Access Denied===
iWHMCS uses the API to communicate with your WHMCS installation. Therefore 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>) > System Settings > [[Administrator Roles]]''' or, prior to WHMCS 8.0, '''Setup > Staff Management > Administrator Roles'''.
* Edit the staff member's role.
* Check the ''API Access'' checkbox.
* Click '''Save Changes'''.

===iWHMCS features other than the home screen require the iWHMCS addon to be purchased===
In order to view pages other than the app home screen it is necessary to purchase the iWHMCS addon for your main WHMCS licence. If you haven't done so already, this can be ordered by logging into our [http://www.whmcs.com/members client area] and selecting '''View Available Addons''' from the navigation bar.

If the addon has already been purchased, please ensure it is associated with the correct licence key. In our client area, navigate to '''Services > Licences & Services''', click "View Details" next to your main WHMCS licence key, select the '''Addons tab''', and ensure the iWHMCS addon is listed. If you're unsure which licence key you're using, navigate to '''Help > [[License Information]]''' inside your WHMCS installation's admin area.

Finally, remote licence checks are performed occasionally, so to have the purchase take immediate effect please force a remote licence check. To do this visit '''Help > [[License Information]]''' and click '''Force Licence Update'''. The action of loading the page will initiate a connection to our licensing server and update your local licence file.

AWHMCS Android App

2023-05-19T15:01:53Z

Lawrence:

<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.whmcs.com/mobile-apps/ 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.

System Environment Guide

2023-05-17T13:36:54Z

Lawrence: /* Required */

WHMCS is compatible with most web server environments. Installing WHMCS in your web environment is usually straight forward. As well, WHMCS is continually providing updates which can seamlessly support environment updates from the upstream providers. However, as new technologies emerge and your current system's environment has access to new updates, it's important that you are aware of how they might affect your WHMCS deployment. This guide is designed help you and your system administrator prepare and manage your environment.

<div class="toclimit-2">__TOC__</div>

== Overview ==
WHMCS is designed for a traditional LAMP (Linux, Apache, MySQL, PHP) environment. The minimum requirements and basic version compatibility related to those sub-systems are provided in our [[System Requirements]].

The development of WHMCS is such that alternative technologies may be viable, however they are not tested and assistance from our Support Team will be limited. For example, if you wish to use NGINX instead of Apache, it may be technically possible. However, our Support will have limited knowledge about how to properly configure NGINX or debug behaviors that are specific to NGINX.

If you require the use of something other than Linux, Apache, or MySQL please consult with your system administrator to evaluate the immediate possibilities for (in)compatibility and long-term viability so that your environment management strategy accommodates for your specific requirements.

== Operating System ==
WHMCS is designed to run in a standard Linux operating/file system. WHMCS relies on PHP for interaction with the file system. In some operating systems (such as Windows) or environments (such as jails or chroots) the file system may have restrictions or inherent behaviors which may be hard to detect or uncommon. When possible, WHMCS provides notices that indicates incompatibility. If you require a different operating/file system, please discuss with your system administrator. Our Support Team is available to provide limited assistance to your system administrator for your custom environment.

Also of note, WHMCS relies heavily on the Linux Cron sub-system to trigger background tasks and perform periodic automation tasks such as deferred provisioning, service synchronization, invoice generation, billing, and more. You may learn more at the [[Crons| crons documentation]].

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Please note, the command line PHP used to invoke the cron will need to meet the same requirements as the [[#PHP| PHP]] binary used by your web server. This includes ini settings and enabled extensions.</div>

== Web Server ==
WHMCS is designed to work with the Apache web server version 2.x. While there are no special Apache configurations required for WHMCS, there are some advantages available to you and your WHMCS deployment that you may wish to consider.

=== Extensions ===

;mod_rewrite
:The Apache mod_rewrite module allows Apache to inspect and modify URLs and redirects through the use of .htaccess files within your web server docroot. WHMCS can create and manage a .htaccess file, and thus generate and consume friendly URLs in various parts of the product. This feature is described in more detail at [[Friendly URLs]].

=== Handler ===
The web server is responsible for all web applications on the server, and thus the Unix permissions granted to the php process (php handler) that operate with your web application are important. Some PHP handlers will execute all php code on the system as the same Unix user (server wide handlers like CGI & mod_php) while other handlers execute the PHP process as a specific user based on domain name (per vhost handlers like suphp, mod_ruid2). Both options are viable for WHMCS. However, as a matter of security, you need to ensure that no other applications on the server, outside your control, executes as the same Unix user. Your system administrator should be able to configure the web server so that this minimum level of security is met, or more conservatively, that the WHMCS web application process is executed by a user that is wholly unique amongst any other application on the server (even those within your control).

=== Directives ===

WHMCS uses configuration directives to alter the web server configuration on a per-directory basis. As Apache is the recommended web server software platform to run WHMCS on, these directives are included via the following .htaccess files.

; ~/.htaccess
: This file contains the mod_rewrite directives responsible for sending routable paths through the index.php file. This in turn allows the internal routing system to function, and furnishes WHMCS with the ability to create consumer friendly URLs. More information can be found on the [[Friendly URLs]] documentation page.

; ~/vendor/.htaccess
: This file prevents access to the ~/vendor directory. This ensures that the web server is not serving file requests directly from this location, and that WHMCS is still capable of accessing the libraries it needs to function. More information can be found on the [[Further_Security_Steps#Vendor_Directory|Further Security Steps]] documentation page.

While other web server technologies are not officially supported, we understand that some users do wish to run WHMCS in environments other than Apache. For those that do, you must ensure that the functionality offered by the aforementioned directives has been implemented by your web server configuration.

How this is achieved depends on the web server itself. If uncertain, then you should consult with your server administrator. As an example, you can find a guide detailing how to secure the vendor directory on the NGINX web server on the [[Nginx Directory Access Restriction]] documentation page.

== Database ==
WHMCS is designed to work with the MySQL database. Binary compatible alternatives (such as MariaDB) should be suitable, however their default configurations and optimizations are likely to be different and you should consult with your system administrator or database administrator.

=== Version Compatibility ===
{{:MySQL Version Support Matrix}}

=== Database Privileges ===
When installing or updating WHMCS, or when activating or deactivating modules, the following privileges are required:
* ALTER
* CREATE
* DROP
* INDEX

For day to day use, only the following database privileges are required. All others may be disabled.
* DELETE
* INSERT
* SELECT
* UPDATE
* LOCK TABLES

If you choose to restrict the privileges for day to day use, don't forget to grant the former privileges so database schema changes and optimizations can be performed by the update process.

=== Database Interaction ===
WHMCS internals utilize the PDO database API. If the PHP environment is v5.6, both a PDO based connection and a MySQL handle will be used for compatibility with legacy code.

If you are developing code for the WHMCS platform, it is recommended that you interact with the database via the [https://developers.whmcs.com/api/internal-api/ Local API], [https://developers.whmcs.com/advanced/db-interaction/ DBAL & ORM], or [[Using Models|Models]]. All three methods will abstract database connection details and system compatibility for you and will be supported by WHMCS for the foreseeable future. The [https://docs.whmcs.com/SQL_Helper_Functions?redirect=no SQL Helper Functions] are still present, although deprecated. Due to their ubiquitous usage, we anticipate supporting them as long as possible but recommend that you use one of the other methods above. You can learn more at [https://developers.whmcs.com/advanced/db-interaction/ Interacting with the Database] on our developer's site.
<div id="PHP_Version"> </div>
== PHP ==
WHMCS is written in PHP. Your environment's PHP will need to be a version supported by the version of WHMCS you are using. In general, this will be one of the PHP versions that is either under active development or is receiving security fixes from the upstream PHP maintainers.

Whenever possible, it is usually preferable to utilize a version of PHP that is under active development. Unfortunately, there can be a number of circumstances that may complicate the viability of using the latest stable release of PHP. These can range from a lack of control panel build support to incompatibility for other web applications on your server to backwards breaking behavior in PHP that inhibit ionCube Loader® support. Regardless, WHMCS always provides support for a security-monitored PHP version available from the PHP maintainers and we are continually prioritizing compatibility with their releases.

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Our [[PHP Upgrade Guide]] outlines the essential steps you can follow in preparation for a PHP upgrade. In WHMCS 7.5 we also provide the [[PHP_Version_Compatibility_Assessment| PHP Version Compatibility Assessment Utility]] designed to scan your WHMCS for any encoded files that may not be compatible for your desired PHP version.</div>

=== Version Compatibility ===
{{:PHP Version Support Matrix}}

=== Extensions ===

WHMCS requires most of the default compiled extensions (for example, PDO, mysqlnd, JSON, libxml, DOM, or Fileinfo). We assume that you will not intentionally disable them in the environment.

You must also compile and enable the following additional extensions:

==== Required ====
; ionCube Loader
: See the [[#ionCube| ionCube Loader]] section below for more detail.
; PDO_MYSQL
: While the basic PDO API extension is compiled by default in PHP, you must also have the PDO MySQL driver enabled so that PDO can communicate with your MySQL database server.
; cURL with SSL Support
: cURL is used when interacting with APIs of external systems such as the WHMCS Licensing & Update servers, payment gateways, servers that host your products, etc. cURL's SSL support must be enabled so that verified and encrypted communication is possible.
<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>WHMCS will check for Curl version 7.36 or above.</div>
; GD2
: GD2 Image Library is used when performing graphic manipulation, such as image thumbnails and PDFs.
; SOAP**
: **SOAP is only required by some specific, but possibly important, modules. It is used when interacting with their corresponding external services, such as EU VAT, OpenSRS, eWay Tokens, etc.
; IMAP**
: **IMAP is only required if you are utilizing support departments which access mailboxes.
; MYSQL**
: ** The original MySQL extension is required if, and only if, your environment uses PHP v5.6.

==== Recommended ====
; iconv
: The iconv extension is for character set conversion, i.e. managing different non-latin characters. If available, this extension provides significant performance improvements and is highly recommended.
; mbstring
: The mbstring extension is for multi-byte character support, i.e managing non-Latin characters and glyphs. If available, this extension provides significant performance, allows for broader support of characters and glyphs common throughout digital communications, and is highly recommended.
; OpenSSL
: OpenSSL is for secure communications and random number generation. If available, this extension will be used and provide significant performance improvements for cryptographic routines.
; GMP
: The functions provided by GMP are used when available. They provide significant performance improvements for when generating cryptographic data.
; BC Math
: The functions provided by BC Math are used when available. They provide performance improvements for when generating cryptographic data.
; Fileinfo
: The functions provided by Fileinfo are used when available. They provide functionalities to aid in determining the content type and encoding of uploaded files.

=== PHP INI Settings ===
; allow_url_fopen
: allow_url_fopen must be enabled for the WHMCS Updater.

<div id="IonCube_Version"> </div>

== ionCube ==

ionCube is a set of encoding and decoding tools that provide obfuscation and performance for PHP software. The decoder tool is a "loader" in the server environment. The encoder tool, an "encoder," is part of PHP developers' publication processes.

WHMCS is encoded with ionCube and requires that you install and enable the ionCube Loader extension in your server environment. We recommend running the latest version of the ionCube Loader for your PHP version. Our [[ioncube Installation Tutorial|ionCube Installation Tutorial]] provides an overview for installing this extension in your environment.

Usually, ionCube will publish a complementing loader several weeks following a new PHP version.

Using this latest loader will afford you two benefits:
* You have the potential for running previously-encoded files using a new base PHP version and running unencoded (raw) PHP code that is compatible with the base PHP version.
* You can run newly-encoded files from a new ionCube Encoder (if one was published).

The ionCube Encoder requires the developer to itemize the PHP versions to support. This helps to mitigate the limitations for supporting certain PHP versions concurrently: it is common for PHP applications to not support the latest PHP version on the initial PHP release date. Applications may also have further requirements about the oldest supported PHP version and the required loader.

Each WHMCS version has always supported at least two PHP versions. Each new version of WHMCS has always supported at least one of the PHP versions supported in the previous WHMCS publication. This perpetual overlap of PHP version support across WHMCS publications means that you always have a path to upgrade your PHP environment without having to update the WHMCS software at the same time. As well, it allows the WHMCS Updater to safely automate updates for your current environment. Providing this overlap is integral to enabling your environment maintenance strategy, giving you the best balance of security, stability and forward compatibility as soon as possible.

=== Version Compatibility ===
{{:IonCube Loader Version Matrix}}

System Environment Guide

2023-05-16T13:22:01Z

Lawrence: /* Required */

WHMCS is compatible with most web server environments. Installing WHMCS in your web environment is usually straight forward. As well, WHMCS is continually providing updates which can seamlessly support environment updates from the upstream providers. However, as new technologies emerge and your current system's environment has access to new updates, it's important that you are aware of how they might affect your WHMCS deployment. This guide is designed help you and your system administrator prepare and manage your environment.

<div class="toclimit-2">__TOC__</div>

== Overview ==
WHMCS is designed for a traditional LAMP (Linux, Apache, MySQL, PHP) environment. The minimum requirements and basic version compatibility related to those sub-systems are provided in our [[System Requirements]].

The development of WHMCS is such that alternative technologies may be viable, however they are not tested and assistance from our Support Team will be limited. For example, if you wish to use NGINX instead of Apache, it may be technically possible. However, our Support will have limited knowledge about how to properly configure NGINX or debug behaviors that are specific to NGINX.

If you require the use of something other than Linux, Apache, or MySQL please consult with your system administrator to evaluate the immediate possibilities for (in)compatibility and long-term viability so that your environment management strategy accommodates for your specific requirements.

== Operating System ==
WHMCS is designed to run in a standard Linux operating/file system. WHMCS relies on PHP for interaction with the file system. In some operating systems (such as Windows) or environments (such as jails or chroots) the file system may have restrictions or inherent behaviors which may be hard to detect or uncommon. When possible, WHMCS provides notices that indicates incompatibility. If you require a different operating/file system, please discuss with your system administrator. Our Support Team is available to provide limited assistance to your system administrator for your custom environment.

Also of note, WHMCS relies heavily on the Linux Cron sub-system to trigger background tasks and perform periodic automation tasks such as deferred provisioning, service synchronization, invoice generation, billing, and more. You may learn more at the [[Crons| crons documentation]].

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Please note, the command line PHP used to invoke the cron will need to meet the same requirements as the [[#PHP| PHP]] binary used by your web server. This includes ini settings and enabled extensions.</div>

== Web Server ==
WHMCS is designed to work with the Apache web server version 2.x. While there are no special Apache configurations required for WHMCS, there are some advantages available to you and your WHMCS deployment that you may wish to consider.

=== Extensions ===

;mod_rewrite
:The Apache mod_rewrite module allows Apache to inspect and modify URLs and redirects through the use of .htaccess files within your web server docroot. WHMCS can create and manage a .htaccess file, and thus generate and consume friendly URLs in various parts of the product. This feature is described in more detail at [[Friendly URLs]].

=== Handler ===
The web server is responsible for all web applications on the server, and thus the Unix permissions granted to the php process (php handler) that operate with your web application are important. Some PHP handlers will execute all php code on the system as the same Unix user (server wide handlers like CGI & mod_php) while other handlers execute the PHP process as a specific user based on domain name (per vhost handlers like suphp, mod_ruid2). Both options are viable for WHMCS. However, as a matter of security, you need to ensure that no other applications on the server, outside your control, executes as the same Unix user. Your system administrator should be able to configure the web server so that this minimum level of security is met, or more conservatively, that the WHMCS web application process is executed by a user that is wholly unique amongst any other application on the server (even those within your control).

=== Directives ===

WHMCS uses configuration directives to alter the web server configuration on a per-directory basis. As Apache is the recommended web server software platform to run WHMCS on, these directives are included via the following .htaccess files.

; ~/.htaccess
: This file contains the mod_rewrite directives responsible for sending routable paths through the index.php file. This in turn allows the internal routing system to function, and furnishes WHMCS with the ability to create consumer friendly URLs. More information can be found on the [[Friendly URLs]] documentation page.

; ~/vendor/.htaccess
: This file prevents access to the ~/vendor directory. This ensures that the web server is not serving file requests directly from this location, and that WHMCS is still capable of accessing the libraries it needs to function. More information can be found on the [[Further_Security_Steps#Vendor_Directory|Further Security Steps]] documentation page.

While other web server technologies are not officially supported, we understand that some users do wish to run WHMCS in environments other than Apache. For those that do, you must ensure that the functionality offered by the aforementioned directives has been implemented by your web server configuration.

How this is achieved depends on the web server itself. If uncertain, then you should consult with your server administrator. As an example, you can find a guide detailing how to secure the vendor directory on the NGINX web server on the [[Nginx Directory Access Restriction]] documentation page.

== Database ==
WHMCS is designed to work with the MySQL database. Binary compatible alternatives (such as MariaDB) should be suitable, however their default configurations and optimizations are likely to be different and you should consult with your system administrator or database administrator.

=== Version Compatibility ===
{{:MySQL Version Support Matrix}}

=== Database Privileges ===
When installing or updating WHMCS, or when activating or deactivating modules, the following privileges are required:
* ALTER
* CREATE
* DROP
* INDEX

For day to day use, only the following database privileges are required. All others may be disabled.
* DELETE
* INSERT
* SELECT
* UPDATE
* LOCK TABLES

If you choose to restrict the privileges for day to day use, don't forget to grant the former privileges so database schema changes and optimizations can be performed by the update process.

=== Database Interaction ===
WHMCS internals utilize the PDO database API. If the PHP environment is v5.6, both a PDO based connection and a MySQL handle will be used for compatibility with legacy code.

If you are developing code for the WHMCS platform, it is recommended that you interact with the database via the [https://developers.whmcs.com/api/internal-api/ Local API], [https://developers.whmcs.com/advanced/db-interaction/ DBAL & ORM], or [[Using Models|Models]]. All three methods will abstract database connection details and system compatibility for you and will be supported by WHMCS for the foreseeable future. The [https://docs.whmcs.com/SQL_Helper_Functions?redirect=no SQL Helper Functions] are still present, although deprecated. Due to their ubiquitous usage, we anticipate supporting them as long as possible but recommend that you use one of the other methods above. You can learn more at [https://developers.whmcs.com/advanced/db-interaction/ Interacting with the Database] on our developer's site.
<div id="PHP_Version"> </div>
== PHP ==
WHMCS is written in PHP. Your environment's PHP will need to be a version supported by the version of WHMCS you are using. In general, this will be one of the PHP versions that is either under active development or is receiving security fixes from the upstream PHP maintainers.

Whenever possible, it is usually preferable to utilize a version of PHP that is under active development. Unfortunately, there can be a number of circumstances that may complicate the viability of using the latest stable release of PHP. These can range from a lack of control panel build support to incompatibility for other web applications on your server to backwards breaking behavior in PHP that inhibit ionCube Loader® support. Regardless, WHMCS always provides support for a security-monitored PHP version available from the PHP maintainers and we are continually prioritizing compatibility with their releases.

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>Our [[PHP Upgrade Guide]] outlines the essential steps you can follow in preparation for a PHP upgrade. In WHMCS 7.5 we also provide the [[PHP_Version_Compatibility_Assessment| PHP Version Compatibility Assessment Utility]] designed to scan your WHMCS for any encoded files that may not be compatible for your desired PHP version.</div>

=== Version Compatibility ===
{{:PHP Version Support Matrix}}

=== Extensions ===

WHMCS requires most of the default compiled extensions (for example, PDO, mysqlnd, JSON, libxml, DOM, or Fileinfo). We assume that you will not intentionally disable them in the environment.

You must also compile and enable the following additional extensions:

==== Required ====
; ionCube Loader
: See the [[#ionCube| ionCube Loader]] section below for more detail.
; PDO_MYSQL
: While the basic PDO API extension is compiled by default in PHP, you must also have the PDO MySQL driver enabled so that PDO can communicate with your MySQL database server.
; cURL with SSL Support
: cURL is used when interacting with APIs of external systems such as the WHMCS Licensing & Update servers, payment gateways, servers that host your products, etc. cURL's SSL support must be enabled so that verified and encrypted communication is possible.
<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>WHMCS will check for Curl version 7.36 or above.</div>
; GD2
: GD2 Image Library is used when performing graphic manipulation, such as image thumbnails and PDFs.
; SOAP**
: **SOAP is only required by some specific, but possibly important, modules. It is used when interacting with their corresponding external services, such as EU VAT, OpenSRS, eWay Tokens, etc.
; IMAP**
: **IMAP is only required if you are utilizing support departments which access mailboxes.
<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>IMAP is only required for WHMCS 7.10 and older.</div>
; MYSQL**
: ** The original MySQL extension is required if, and only if, your environment uses PHP v5.6.

==== Recommended ====
; iconv
: The iconv extension is for character set conversion, i.e. managing different non-latin characters. If available, this extension provides significant performance improvements and is highly recommended.
; mbstring
: The mbstring extension is for multi-byte character support, i.e managing non-Latin characters and glyphs. If available, this extension provides significant performance, allows for broader support of characters and glyphs common throughout digital communications, and is highly recommended.
; OpenSSL
: OpenSSL is for secure communications and random number generation. If available, this extension will be used and provide significant performance improvements for cryptographic routines.
; GMP
: The functions provided by GMP are used when available. They provide significant performance improvements for when generating cryptographic data.
; BC Math
: The functions provided by BC Math are used when available. They provide performance improvements for when generating cryptographic data.
; Fileinfo
: The functions provided by Fileinfo are used when available. They provide functionalities to aid in determining the content type and encoding of uploaded files.

=== PHP INI Settings ===
; allow_url_fopen
: allow_url_fopen must be enabled for the WHMCS Updater.

<div id="IonCube_Version"> </div>

== ionCube ==

ionCube is a set of encoding and decoding tools that provide obfuscation and performance for PHP software. The decoder tool is a "loader" in the server environment. The encoder tool, an "encoder," is part of PHP developers' publication processes.

WHMCS is encoded with ionCube and requires that you install and enable the ionCube Loader extension in your server environment. We recommend running the latest version of the ionCube Loader for your PHP version. Our [[ioncube Installation Tutorial|ionCube Installation Tutorial]] provides an overview for installing this extension in your environment.

Usually, ionCube will publish a complementing loader several weeks following a new PHP version.

Using this latest loader will afford you two benefits:
* You have the potential for running previously-encoded files using a new base PHP version and running unencoded (raw) PHP code that is compatible with the base PHP version.
* You can run newly-encoded files from a new ionCube Encoder (if one was published).

The ionCube Encoder requires the developer to itemize the PHP versions to support. This helps to mitigate the limitations for supporting certain PHP versions concurrently: it is common for PHP applications to not support the latest PHP version on the initial PHP release date. Applications may also have further requirements about the oldest supported PHP version and the required loader.

Each WHMCS version has always supported at least two PHP versions. Each new version of WHMCS has always supported at least one of the PHP versions supported in the previous WHMCS publication. This perpetual overlap of PHP version support across WHMCS publications means that you always have a path to upgrade your PHP environment without having to update the WHMCS software at the same time. As well, it allows the WHMCS Updater to safely automate updates for your current environment. Providing this overlap is integral to enabling your environment maintenance strategy, giving you the best balance of security, stability and forward compatibility as soon as possible.

=== Version Compatibility ===
{{:IonCube Loader Version Matrix}}

System Requirements

2023-05-16T13:18:36Z

Lawrence:

Most current web servers* that use PHP and MySQL® can run WHMCS.

The following table shows the minimum and recommended system requirements for running '''WHMCS 8.0''' and later.

<div class="docs-alert-danger">
Looking for the requirements for the earlier WHMCS 7.5 - 7.10 versions? [[Version 7.5-7.10 System Requirements|Click here.]]
</div>

{| class="table table-striped"
! '''Requirement'''
! '''Minimum'''
! '''Recommended'''
|-
| PHP Version
| 7.2
| WHMCS 8.0 through 8.5 — ''Latest'' 7.4 Release <br /> WHMCS 8.6 and later — ''Latest'' 7.4 or 8.1 Release
|-
| PHP Memory Limit
| 64MB
| 128MB**
|-
| PHP Database Extension
| PDO
| PDO
|-
| PHP Extensions
| Curl with SSL***<br/>
GD2 Image Library<br/>
JSON Support<br />
XML<br/>
| BC Math<br/>
Fileinfo<br/>
GMP<br/>
Iconv<br/>
Intl<br/>
MBString<br/>
OpenSSL***<br/>
SOAP<br/>
|-
| MySQL Version
| 5.2.0
| ''Latest'' 5.7
|-
| ionCube Loader®
| 10.4.5 or later for PHP 7.2 through 7.4<br/>
12.0.1 or later for PHP 8.1
| The latest ionCube Loader version for your PHP version
|}

<div class="docs-alert-info">
View all supported '''PHP versions''' for each version of WHMCS in the [[PHP Version Support Matrix]].
</div>

<div class="docs-alert-warning">
While these are the minimum requirements, we '''''strongly recommend using the latest available, stable releases of all software and extensions'''''. Recommendations are correct as at September 2022.
</div>

<div class="docs-alert-success">
For details on the recommended system environment configurations (OS, web server, database engine, PHP, and ionCube Loader), see the [[System Environment Guide]].
</div>

<nowiki>* We validate WHMCS to run in Linux based environments running the Apache web server. Other environments like Windows-based configurations may experience compatibility issues with which Technical Support cannot assist.</nowiki>

<nowiki>** Memory requirements vary depending upon the size and volume of activity in an installation. Your exact requirements may differ.</nowiki>

<nowiki>*** As part of PCI compliance, a SSL library capable of TLS 1.2 may be required. If using OpenSSL, version 1.0.1c or newer is recommended. </nowiki>

Domain Registrars

2023-04-04T13:57:58Z

Lawrence: /* Supported Domain Registrars */

WHMCS allows you to configure automated domain registration and management and manage many domain-related functions.

You can access this feature 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'''.

==Configure a Domain Registrar==

To configure a registrar:

# If it is not already active, activate the desired registrar. To do this, click '''Activate''' for that registrar in the list. A success message and the applicable registrar settings will appear.
# If the registrar module is already active, click '''Configure''' for that registrar in the list. The applicable registrar settings will appear.
# Enter or update the relevant details for your account with that registrar. <div class="docs-alert-info">Each registrar that WHMCS supports has specific instructions and requirements (see below).</div>

<div class="docs-alert-warning">
Make certain that you set the default nameservers that WHMCS uses for domain-only registrations 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'''.
</div>

===Supported Domain Registrars===

<table class="table table-striped">
<tr>
<td>[[101Domain]]</td>
<td>[[Affordable Domains]]</td>
<td>[[BizCN]]</td>
</tr>
<tr>
<td>[[CentralNic Reseller]]</td>
<td>[[Distribute IT]]</td>
<td>[[DotDNS]]</td>
</tr>
<tr>
<td>[[Email]]</td>
<td>[[Enom]]</td>
<td>[[ENom New TLDs]]</td>
</tr>
<tr>
<td>[[GMO Internet]]</td>
<td>[[GoDaddy]]</td>
<td>[[Heart Internet Domains]]</td>
</tr>
<tr>
<td>[[HexoNet|HEXONET]]</td>
<td>[[InternetBS]]</td>
<td>[[IPMirror]]</td>
</tr>
<tr>
<td>[[Namecheap]]</td>
<td>[[NetEarthOne]]</td>
<td>[[Nominet]]</td>
</tr>
<tr>
<td>[[OnlineNIC]]</td>
<td>[[OpenSRS]]</td>
<td>[[OVH]]</td>
</tr>
<tr>
<td>[[Realtime Register]]</td>
<td>[[Registercom]]</td>
<td>[[Regstereu]]</td>
</tr>
<tr>
<td>[[ResellerCamp]]</td>
<td>[[ResellerClub]]</td>
<td>[[ResellOne]]</td>
</tr>
<tr>
<td>[[RRPProxy]]</td>
<td>[[Stargate]]</td>
<td>[[TPP Wholesale]]</td>
</tr>
<tr>
<td>[[TransIP]]</td>
<td>[[VentraIP Wholesale]]</td>
<td>[[WebNIC]]</td>
</tr>
</table>

==Deactivate a Registrar==

To deactivate an active registrar, click '''Deactivate''' for that registrar in the list and then click '''OK'''.

==Automatic Registration==

WHMCS allows you to specify which registrar to use on a per-TLD basis. You can use multiple suppliers for different TLDs in order to reduce your total costs.

To do this, select the desired registrars for each TLD from the '''Auto Registration''' menu at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Domain Pricing]]''' or, prior to WHMCS 8.0, '''Setup > Domain Pricing'''.

==Domain Synchronisation==

If you wish to sync the expiry date, next due date, and status with your registrar for your domains, you can do this using the '''[[Domain Synchronisation|Domain Sync Settings]]''' section at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''.

System Requirements

2023-03-28T13:39:44Z

Lawrence:

Most current web servers* that use PHP and MySQL® can run WHMCS.

The following table shows the minimum and recommended system requirements for running '''WHMCS 8.0''' and later.

<div class="docs-alert-danger">
Looking for the requirements for the earlier WHMCS 7.5 - 7.10 versions? [[Version 7.5-7.10 System Requirements|Click here.]]
</div>

{| class="table table-striped"
! '''Requirement'''
! '''Minimum'''
! '''Recommended'''
|-
| PHP Version
| 7.2
| WHMCS 8.0 through 8.5 — ''Latest'' 7.4 Release <br /> WHMCS 8.6 and later — ''Latest'' 7.4 or 8.1 Release
|-
| PHP Memory Limit
| 64MB
| 128MB**
|-
| PHP Database Extension
| PDO
| PDO
|-
| PHP Extensions
| Curl with SSL***<br/>
GD2 Image Library<br/>
JSON Support<br />
XML<br/>
| BC Math<br/>
Fileinfo<br/>
GMP<br/>
Iconv<br/>
IMAP<br/>
Intl<br/>
MBString<br/>
OpenSSL***<br/>
SOAP<br/>
|-
| MySQL Version
| 5.2.0
| ''Latest'' 5.7
|-
| ionCube Loader®
| 10.4.5 or later for PHP 7.2 through 7.4<br/>
12.0.1 or later for PHP 8.1
| The latest ionCube Loader version for your PHP version
|}

<div class="docs-alert-info">
View all supported '''PHP versions''' for each version of WHMCS in the [[PHP Version Support Matrix]].
</div>

<div class="docs-alert-warning">
While these are the minimum requirements, we '''''strongly recommend using the latest available, stable releases of all software and extensions'''''. Recommendations are correct as at September 2022.
</div>

<div class="docs-alert-success">
For details on the recommended system environment configurations (OS, web server, database engine, PHP, and ionCube Loader), see the [[System Environment Guide]].
</div>

<nowiki>* We validate WHMCS to run in Linux based environments running the Apache web server. Other environments like Windows-based configurations may experience compatibility issues with which Technical Support cannot assist.</nowiki>

<nowiki>** Memory requirements vary depending upon the size and volume of activity in an installation. Your exact requirements may differ.</nowiki>

<nowiki>*** As part of PCI compliance, a SSL library capable of TLS 1.2 may be required. If using OpenSSL, version 1.0.1c or newer is recommended. </nowiki>

Clients:Users Tab

2023-03-28T13:29:55Z

Lawrence: /* Password Reset */

{{Client Management}}

In WHMCS 8.0 and later, [[Users and Accounts|users]] can own multiple client accounts, allowing a single user to switch between accounts and manage each separately.

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

<div class="docs-alert-warning">
'''Disable Client Area User Management''' in the '''[[Other Tab|Other]]''' tab at
'''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' disables user management for account owners and prevents them from inviting new users.
</div>

==Associate a User==

To add a new user, you can use this tab or [https://help.whmcs.com/m/managing/l/1275668-adding-and-managing-users the Client Area].

<div class="docs-alert-info">
If you send an invitation to an email address for an existing account, they can access the client account using their existing login credentials. If the email address does not correspond to an existing account, they can create one.
</div>

To associate a user and client account:

# Click '''Associate User'''.
# Choose an account from '''Select User''' or enter an email address.
# Select the desired '''Permissions''' settings or select '''Check All''' to select all of them.
# Toggle '''Send Invite''' to ''Yes'' to send an invitation email.
# Click '''Invite User'''.

After you add or associate a user, they will display in '''Users''' in the client's profile. Click '''Resend Invite''' to resend the invitation email, or click '''Cancel Invite''' to cancel the invitation.

==Manage==

Click '''Manage''' to manage the user within the context of this account.

To manage individual user information outside of the context of an associated account, go to '''Clients > [[Manage Users]]'''.

===Manage Users===

To manage a user's information or permissions for the account, click '''Manage''' for that user and select '''Manage User'''. You can update the user's name, email address, and permissions, disable [[Two-Factor Authentication]] or security questions, and transfer account ownership to the user.

Disabling security questions for the user removes their current security question and answer and allows them to set a new one in the Client Area.

===Password Reset===

To reset a user's password, click the arrow next to '''Manage User''' for that user and select '''Password Reset'''. Click '''OK''' on the confirmation window that appears and the system will send a password reset email to the user.

===Remove===

To remove a user's access to a client's account, click '''Manage''' for that user and select '''Remove'''. This will remove access to the account, but will not delete the user from WHMCS.

Affiliates

2023-03-28T13:28:31Z

Lawrence: /* Affiliate Codes and Links */

Affiliates help generate revenue by referring customers to your business. WHMCS includes a comprehensive affiliate system with support for one-time and recurring commissions, either in percentages or fixed values. It also includes payout delays, minimum withdrawal limits, and live statistics and information for affiliates in the Client Area.

You can access this feature at '''Clients > [[Manage Affiliates]]'''.

== Commissions ==

Affiliates earn commission for products and services (including configurable options) only. They can't earn commission on:

* Domain names.
* [[Product Addons]].
* Upgrade orders. <div class="docs-alert-info">Any recurring commissions will increase with new renewal prices.</div>
* Manually-created invoices.
* [[Usage_Billing|Usage billing]], invoiced in a arrears.

== Affiliate System Configuration ==

Before you can use the affiliate system, you must:

* Configure the settings in the '''[[Affiliates_Tab|Affiliates]]''' 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'''.
* Activate affiliate status for the desired clients in the [[Clients:Summary_Tab|client profile '''Summary''' tab]].

=== Setting Overrides ===

You can overide these settings on a ''per-client'' basis and set a specific commission rate for an individual affiliate at '''Clients > [[Manage Affiliates]]'''.

You can override these settings on a ''per-product'' basis when you configure a product in the '''Other''' 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 > Product/Services'''.

=== Setting Commission Per-Product ===

To offer a higher commission on a certain product, edit the product and go to the Other 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 > Product/Services'''.

From here you can choose a percentage or fixed amount commission. Selecting the One Time Payout checkbox will give the commission only once. The default commission setting for WHMCS is recurring.

It is possible to disable commission entirely for an individual product from this page by selecting the '''No Commission''' option. This setting takes priority over the default commission. However, if you have set either the client or the product commission to One Time Payout, that setting will override this.

=== Setting Commission Per-Client ===

To offer a unique commission, click the "'View Affiliate Details'" link on the "client's [[Clients:Summary_Tab|'''Summary''']] tab" and you can set the commission as above. This setting will take priority over all others. However, if you have set either the client or the product commission to One Time Payout, that setting will override this.

=== Delays and Reversals ===

WHMCS includes tools to help you prevent losses due to disputes, cancellations, or refunds on transactions for which you pay commissions.

The '''Affiliate Commission Delay''' setting at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[General Settings]]''' or, prior to WHMCS 8.0, '''Setup > General Settings''' helps you avoid this by delaying commission payment for a set number of days after the transaction.
* This setting applies to commissions for both initial orders and renewals.
* At the time of payment, the affiliate's '''Pending Commissions Balance''' will increase by the amount of commission for the order but their '''Available to Withdraw Balance''' will not.
* WHMCS only awards commission if the product or service is in the '''Active''' status when payout would occur according to your settings.
** This is either at the end of the delay period or, if you did not set a delay period, immediately.
** If it is in another status, the commission will be removed and can only be awarded manually.

In WHMCS 8.3 and later, you can also perform reversals on commission.
* WHMCS can reverse commissions when you refund the invoice that incurred the affiliate commission.
** When you perform a full refund, WHMCS automatically reverses all of the associated commissions.
** When you perform a partial refund, you can choose whether to also reverse the commission. You cannot, however, choose an amount of the commission to reverse. Reversing the commission must reverse the entire amount.
* If you choose '''not''' to perform a commission reversal, the commission payment will not be affected.

<div class="docs-alert-info">
If you paid a commission before upgrading to WHMCS 8.3, WHMCS will not present the option to reverse commissions.
</div>

== Working with Affiliates ==

Before a client can receive commissions, they must become an activated affiliate.

* You can activate affiliates in their client profile's '''Summary''' tab. To do this, navigate to the [[Clients:Summary_Tab|client profile '''Summary''' tab]] and click '''Activate as Affiliate''' under '''Other Actions'''.
* After you have enabled the affiliate system as described above, clients can also activate affiliate status for themselves in the Client Area.

=== Managing Affiliates ===

To view and manage affiliates and create manual commission payments and withdrawals, go to '''Clients > [[Manage Affiliates]]'''.

<div class="docs-alert-info">
You '''must''' also configure the settings in the [[#Affiliate System Configuration|Affiliate System Configuration]] section above. Otherwise, affiliate information will ''not'' display in the Client Area and the affiliate system will not function.
</div>

=== Assigning an Affiliate to an Existing Order ===

To assign an affiliate to an existing referral-free order that contains a service:

# Go to '''Orders > List'''.
# Locate the order you want to assign to the affiliate.
# Click the '''Order ID''' number to open the details for that order.
# Click '''Manual Assign''' in the '''Affiliate''' section.
# From the menu that appears, select the affiliate to assign to the order. Alternately, start typing the name of the desired affiliate.
# Click '''Save'''.

=== Unassigning an Affiliate from an Order ===

To unassign an affiliate from an order:

# Visit '''Clients > Manage Affiliates'''.
# Select the order's assigned affiliate.
# Select the '''Referred Signups''' tab.
# Delete the relevant signup using the red button on the right hand side.
You can now assign the order to another affiliate using the [[#Assigning_an_Affiliate_to_an_Existing_Order|Assigning an Affiliate to an Existing Order]] section above.

=== Paying Commission for a Paid Order ===

You may wish to apply an affiliate to an order after it is paid, in which case the affiliate has missed the initial commission for that order.

To correct this:

# Use the steps above to assign the affiliate to the order.
# Go to '''Clients > [[Manage Affiliates]]'''.
# In the '''Referrals''' tab, click '''Manual Payout''' for that order.

WHMCS will perform the necessary steps to credit the affiliate.

== Affiliate Codes and Links ==

WHMCS generates a unique code for each affiliate to use on their website. For example:

<nowiki>https://www.example.com/aff.php?aff=001</nowiki>

Affiliates can obtain their unique link via the Client Area. To view the link, they can log in to the Client Area and click '''Affiliates''' in the main menu.

When a visitor follows an affiliate link, the system will redirect them to the URL that you specified for '''Domain''' in the '''[[General_Tab|General]]''' 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 will save a cookie in their browser. If the visitor places an order for a product or service with the cookie present, the affiliate will earn a commission. By default, the cookie persists for three months.

=== Affiliate Linking Code ===

You can specify '''Affiliate Link''' code in the '''[[Affiliates Tab|Affiliates]]''' 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'''. For example:

<source lang="html4strict">
<a href="[AffiliateLinkCode]"><img src="http://www.yourcompany.com/banners/468x60banner.gif" width="468" height="60" border="0"></a><br>
<(a href="[AffiliateLinkCode]")><(img src="http://www.yourcompany.com/banners/468x60banner.gif" width="468" height="60" border="0")><(/a)><br><br>
<a href="[AffiliateLinkCode]"><img src="http://www.yourcompany.com/banners/120x60banner.gif" width="120" height="60" border="0"></a><br>
<(a href="[AffiliateLinkCode]")><(img src="http://www.yourcompany.com/banners/120x60banner.gif" width="120" height="60" border="0")><(/a)><br><br>
</source>

If you enter this code, it will display the image preview of the banner first and then the code below it for the affiliate to use. The <tt><(</tt> and <tt>)></tt> are parts of a special syntax that you '''must''' use to ensure that the code is '''not''' executed as HTML. WHMCS modifies this during display to cause it to appear as normal HTML.

You can add advanced link code directly to the <tt>affiliates.tpl</tt> template file in your active template folder using the <tt>{$referrallink}</tt> template field wherever you want to include the affiliate's unique referral URL.

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

=== Linking to a Product Group ===

You can link directly to the order form for a specific product group. To do this, append <tt>&gid=x</tt> to the end of the <tt>[AffiliateLinkCode]</tt>, where <tt>x</tt> is the ID of the product group. For example:

<source lang="html4strict">
<a href="[AffiliateLinkCode]&gid=2"><img src="http://www.yourcompany.com/banners/468x60banner.gif" width="468" height="60" border="0"></a><br> <(a href="[AffiliateLinkCode]&gid=2")><(img src=http://www.yourcompany.com/banners/468x60banner.gif" width="468" height="60" border="0")><(/a)>
</source>

=== Linking to a Product ===

You can link directly to the order form for a specific product. To do this, append <tt>&pid=x</tt> to the end of the <tt>[AffiliateLinkCode]</tt>, where <tt>x</tt> is the product ID. For example:

<source lang="html4strict">
<a href="[AffiliateLinkCode]&pid=2"><img src="http://www.yourcompany.com/banners/468x60banner.gif" width="468" height="60" border="0"></a><br> <(a href="[AffiliateLinkCode]&pid=2")><(img src=http://www.yourcompany.com/banners/468x60banner.gif" width="468" height="60" border="0")><(/a)>
</source>

=== Linking to the Cart ===

You can link directly to the cart. To do this, append <tt>&gocart=true</tt> to the end of the <tt>[AffiliateLinkCode]</tt>. For example:

<source lang="html4strict">
<a href="[AffiliateLinkCode]&gocart=true"><img src="http://www.yourcompany.com/banners/468x60banner.gif" width="468" height="60" border="0"></a><br> <(a href="[AffiliateLinkCode]&gocart=true")><(img src=http://www.yourcompany.com/banners/468x60banner.gif" width="468" height="60" border="0")><(/a)>
</source>

=== Linking to the Registration Form ===

You can link directly to the registration form. To do this, append <tt>&register=true</tt> to the end of the <tt>[AffiliateLinkCode]</tt>. For example:

<source lang="html4strict">
<a href="[AffiliateLinkCode]&register=true"><img src="http://www.yourcompany.com/banners/468x60banner.gif" width="468" height="60" border="0"></a><br> <(a href="[AffiliateLinkCode]&register=true")><(img src=http://www.yourcompany.com/banners/468x60banner.gif" width="468" height="60" border="0")><(/a)>
</source>

== Affiliate Cookies ==

The affiliate link cookie lasts for three months on the user's computer by default. You can change the cookie duration by editing the <tt>aff.php</tt> file.

Line 24 controls the creation of the cookie and how long it lasts:

<source lang="php">
Cookie::set('AffiliateID',$aff,'3m');
</source>

When editing this line, only alter the final argument (<tt>3m</tt>).

The final argument defines the lifetime of the cookie using [http://php.net/manual/en/function.time.php PHP Timestamps]. For convenience, we offer a helper when defining months. When you require months, specify the number of months and append <tt>m</tt> as in the example above.

The following examples are commonly-used lifetimes:

===== One Day =====

<source lang="php">
Cookie::set('AffiliateID', $aff, time() + (24*60*60));
</source>

===== Seven Days =====

<source lang="php">
Cookie::set('AffiliateID', $aff, time() + (7*24*60*60));
</source>

===== Fourteen Days =====

<source lang="php">
Cookie::set('AffiliateID', $aff, time() + (14*24*60*60));
</source>

===== One Month =====

<source lang="php">
Cookie::set('AffiliateID', $aff, '1m');
</source>

== Affiliate System Commission Logic ==

The affiliate system uses the following logic when processing commissions:

=== Setup Fees ===

If there is a setup fee, the initial commission will include it. Then, the system bases recurring commissions on the product's '''[[Products_and_Services#Pricing Recurring Amount|pricing recurring amount]]'''.

=== Promotions ===

If a referred client uses a promotional code when signing up and you have configured a percentage commission, the system will reduce the value of the commission. If you have configured a fixed amount commission, they will still receive the full commission.

For example, if someone uses an affiliate's ''three months free'' promotional code, the affiliate gets the commission based on the first payment amount. Then, they receive recurring amounts according to the product's settings. In this example, the affiliate would receive a percentage of ''zero'' for the first three months.

=== Product Upgrades and Downgrades ===

If a referred client upgrades or downgrades their product, the system will adjust the affiliate's future commissions to match the price of the new product.

* This won't affect commission payments that the affiliate has already earned.
* There is no commission on the upgrade or downgrade order itself.
* This does not apply to one-time commissions.

=== Multi Currency ===

When you pay percentage commissions, WHMCS will convert the value in the purchaser's currency to the affiliate's currency using the current exchange rate. If you select to pay a fixed amount, it pays the same amount in any currency.

The system converts the '''Affiliate Bonus Deposit''' amount and '''Affiliate Payout Amount''' into the affiliate's currency.

General Tab

2023-03-28T13:24:49Z

Lawrence: /* Domain */

{{General Settings}}<br/>

The '''General''' tab allows you to configure basic settings within WHMCS.

You can access this 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'''.

===Company Name===
Enter your company name as you wish it to appear throughout the WHMCS Admin and Client Areas.

===Email Address===
This is the default email address that will appear as the sender on all of the email that WHMCS sends to you and your customers.

===Domain===
The URL for the domain that hosts your WHMCS installation. When a visitor follows an affiliate link, they will be redirected to this URL.

===Logo URL===
The URL for the logo image that will appear in email messages, on invoices, and in the WHMCS Client Area.

===Pay To Text===
The text to display on invoices as the ''Pay To'' details.

===WHMCS System URL===
This setting defines the URL to use to access your WHMCS installation. This is based on the location of the files on your server. If possible, WHMCS attempts to set this value automatically during installation. If you use the command line for installation, WHMCS will prompt you for this value. For example, <tt>http://www.example.com/members/</tt>.

We recommend installing an SSL certificate. This will let you enter the SSL URL to enable encrypted connections between WHMCS and your customers and between your staff and the Admin Area. For example, <tt>https://www.example.com/members/</tt>.

For more information about including this value in custom development, see [[WHMCS Base URL Template Variable]].

===System Theme===
The system theme that you want to use for WHMCS's Client Area. We ship two by default:

* ''Twenty-One'' was introduced in WHMCS 8.1. We recommend that you use this system theme. For more information, see [[New Twenty-One Client Area Theme]].
* ''Six'' was introduced in WHMCS 6.0. We plan to remove this system theme in a future WHMCS version.

In WHMCS 8.1 and higher, when you select a '''System Theme''', WHMCS will validate it for compatibility with the order form templates you use.

For information on developing your own custom system theme, see [https://developers.whmcs.com/themes/ Themes] in our [https://developers.whmcs.com/ Developer Documentation].

===Limit Activity Log===
The maximum number of system-related entries to store in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' or, prior to WHMCS 8.0, '''Utilities > Logs'''. System-related entries display the user of '''System/Automated''' and client of '''None'''.

WHMCS purges system-related entries daily during the execution of the cron, when the activity log is viewed within the Admin Area, or when the '''Limit Activity Log''' setting is modified.

<div class="docs-alert-info">
Entries for specific clients are stored indefinitely for auditing purposes. You can prune client-specific log entries at '''Utilities > System > [[System_Utilities#System_Cleanup|System Cleanup]]'''.
</div>

===Records to Display per Page===
The number of records to display in the '''Clients''' list, lists of invoices, and other lists in WHMCS.

===Maintenance Mode===
Enabling this option will prevent your customers from accessing the Client Area and display the '''Maintenance Mode Message''' (or redirect to another URL, if you enter a '''Maintenance Mode Redirect URL'''.

<div class="docs-alert-warning">
Admins will still be able to see the client area. Both the API and hooks will continue to function unobstructed while '''Maintenance Mode''' is enabled.
</div>

===Maintenance Mode Message===
If you enable '''Maintenance Mode''', your customers will see the message you enter here in the Client Area.

===Maintenance Mode Redirect URL===
When you enter a URL here, clients will be redirected there when '''Maintenance Mode''' is enabled instead of seeing the maintenance message.

===Friendly URLs===

The Friendly URLs feature alters WHMCS URLs to use a human-readable format. For more information, see [[Friendly URLs]].

You can choose the following URI path modes:

* '''Full Friendly Rewrite''' — This option will generate highly systematic URLs, which are excellent for search engines and visitors alike. They are completely decoupled from the file system.
** This mode is only valid in environments that support Apache <tt>mod_rewrite</tt> behavior.
** For example: <tt><nowiki>http://example.com/knowledgebase</nowiki></tt>
* '''Friendly index.php''' — This option will generate systematic URLs but is coupled to the filesystem. It is a good option for search engines and visitors if your environment does not support Apache <tt>mod_rewrite</tt>.
** This mode is only valid in environments that support Apache <tt>AcceptPathInfo</tt> behavior.
** For example: <tt><nowiki>http://example.com/index.php/knowledgebase</nowiki></tt>
* '''Basic URLs''' — This option will generate URLs that all web environments support. Most search engine technologies are capable of moderate to advanced indexing when analyzing these types of URLs. However, some internet users find these URLs unattractive and cumbersome.
** For example: <tt><nowiki>http://example.com/index.php?rp=/knowledgebase</nowiki></tt>

When you select an option, the system saves it automatically. If it does not match the detected setting (see below) it displays '''Manual Override''' next to the setting.

==== Detected Mode ====

WHMCS automatically detects the best option for your server environment and highlights it with a green background.

* To detect the best option again, click the circular arrow icon. This performs an environment detection and immediately updates your '''Friendly URLs''' settings.
* If the '''Auto-Managed Rewrite''' setting is not enabled and the system detects that modifications to your rewrite file (<tt>.htaccess</tt>) may occur during the optimization routine, the system will prompt you to enable it before any changes are applied.

==== Advanced Settings ====

Click '''Advanced Settings''' to further customize how this feature behaves. We only recommend changing the advanced settings if you are confident maintaining your own <tt>mod_rewrite</tt> rules.

* The '''Path Mode''' tab allows you to manually override the system-detected URI path mode and shows which modes are supported by your environment.
* The '''Rewrite File''' tab allows you to manually select how WHMCS should control the rewrite file (<tt>.htaccess</tt>) as well as a copy of the WHMCS rewrite rules. Rewrite rules alter inbound HTTP requests so that the application can effectively process Friendly URLs.

===== Path Mode =====

The '''Path Mode''' tab allows you to manually override the system-detected URI Path Mode and shows which modes are known to be support by your environment.

[[File:UriPathModeMgmt.png|550px]]

The settings here perform the same result as the '''Simple Mode Selection''' but with more explicit control. You may enable the manual override option while selecting a '''URI Path Mode''' that is the same as the system detected value.

===== Rewrite File =====

The '''Rewrite File''' tab allows you to manually select how WHMCS should control the rewrite file (<tt>.htaccess</tt>) as well as a copy of the WHMCS rewrite rules. Rewrite rules alter inbound HTTP requests so that the application can effectively process friendly URLs.

[[File:UriMgmtRewriteRuleTab.png|550px]]

<div class="docs-alert-warning">
<span class="title">Upgrade to WHMCS 7.2</span><br />
When you upgrade to WHMCS 7.2, WHMCS will perform an evaluation of your current environment. For more information, see [[Friendly URLs]].
</div>

=====Auto-Managed Rewrite=====

When you enable '''Auto-Managed Rewrite''', the system applies new rules from a WHMCS update to the <tt>.htaccess</tt> file of the WHMCS root directory during the update.

Manually enabling or disabling '''Auto-Managed Rewrite''' will not automatically reevaluate or synchronize the WHMCS ruleset.

===== Synchronize =====

If the current contents of the <tt>.htaccess</tt> file are not in sync with the WHMCS ruleset, click '''Synchronize''' to synchronize it.

When the system applies rules to the <tt>.htaccess</tt> file, it places them between comment markers that clearly indicate the beginning and end of the WHMCS ruleset. If you require custom rulesets for other destinations within the WHMCS root directory, make sure that you place them before or after these comment markers.

<div class="docs-alert-info">
  WHMCS cannot automatically detect compatibility with other rules. WHMCS Technical Support can only provided limited suggestions based on WHMCS’s requirements.
</div>

===WHMCS Rules===

A copy of the WHMCS ruleset for your current version of WHMCS is displayed for your inspection and application. Some web environments provide alternative mechanisms for performing URI rewrites on inbound HTTP requests. Your system administrative staff should be able to update your alternative web environment based on this information to fully utilize the Friendly URLs feature of WHMCS.

<div class="docs-alert-info"><i class="fa fa-question-circle"></i> These .htaccess rules apply to WHMCS version 7.2 and above.</div>
<pre>
### BEGIN - WHMCS managed rules - DO NOT EDIT BETWEEN WHMCS MARKERS ###
<IfModule mod_rewrite.c>
RewriteEngine on

# RewriteBase is set to "/" so rules do not need updating if the
# installation directory is relocated. It is imperative that
# there is also a RewriteCond rule later that can effectively get
# the actual value by comparison against the request URI.
#
# If there are _any_ other RewriteBase directives in this file,
# the last entry will take precedence!
RewriteBase /

# Redirect directories to an address with slash
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^(.+[^/])$ $1/ [R]

# Send all remaining (routable paths) through index.php
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
# Determine and use the actual base
RewriteCond $0#%{REQUEST_URI} ([^#]*)#(.*)\1$
RewriteRule ^.*$ %2index.php [QSA,L]
</IfModule>
### END - WHMCS managed rules - DO NOT EDIT BETWEEN WHMCS MARKERS ###
</pre>

===== IIS Environments =====

To enable Friendly URLs for IIS environments:

# Ensure that the URL rewrite module [http://learn.iis.net/page.aspx/460/using-the-url-rewrite-module/ is installed for IIS].
# Open '''IIS Manager'''.
# Go to the site you want to add the rule to.
# In the right pane, double-click and select ''urlrewrite''.
# On the right side inbound rules, select ''import rules''.
# Extract the <tt>mod_rewrite</tt> rules from the WHMCS's rewrite file at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings''', in the '''Advanced Settings''' section.
# Paste those rules into the '''rewrite rules''' field.
# Click '''Apply'''.

Stripe SEPA

2023-02-07T14:44:45Z

Lawrence: /* Payment Workflow */

== About this Module ==

<div class="docs-alert-info">
We added this module in WHMCS 7.9.
</div>

The Stripe SEPA payment gateway module is available in WHMCS.
{{gateways
| type = token
| recurring = yes
| onetime = yes
| refunds = yes
| deletecc = yes
}}
== Adding the Stripe SEPA Payment Gateway ==

To set up the Stripe SEPA 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 '''Stripe SEPA'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Enter your Stripe credentials.
#* If you currently also use the [[Stripe]] payment gateway, you can check '''Use Stripe Configuration''' to use your existing API keys.
#* You can find your credentials in [https://dashboard.stripe.com/account/apikeys the Stripe portal].
#* Do not enter a value for the Webhook Secret Key. The system will generate it automatically.
#** The Stripe SEPA module requires a valid Webhook and Secret Key in order for payments to be recognised and automatically applied to invoices.
#** If you modify the secret key for the webhook at Stripe, you must also update it in WHMCS.
#* Do not enter a value for '''Webhook Endpoint Secret'''.
# Click '''Save Changes'''.

=== Test Mode ===

This module does not support test mode.

== Transaction Fees ==

Stripe returns transaction fees in the default currency of the Stripe account. If you have a different default currency in WHMCS, you must ensure you have configured the currency of your Stripe account in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, ''Setup > Payments > Currencies'' along with a valid exchange rate to allow WHMCS to be able to convert the fee into your other currencies.</div>

== Supported Currencies ==

Stripe SEPA '''only''' supports the EUR currency. For other currencies, the Stripe SEPA option won't appear when placing orders or paying invoices.

==Payment Workflow==

This module supports automated recurring and on-demand billing.

SEPA Direct Debit is a pull-based, reusable, and asynchronous payment method. This means that it can take up to 14 business days to confirm the success or failure of a payment after you initiate a debit from the customer’s account, though the average is five business days.. The invoice will be placed in Payment Pending until the payment has cleared.

When making a 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 Stripe and is never stored in your local WHMCS installation.

The Stripe API is used for refunds and obtaining transaction information.

==Troubleshooting==

''N/A''

{{modules}}

Stripe SEPA

2023-02-07T14:44:21Z

Lawrence: /* Adding the Stripe SEPA Payment Gateway */

== About this Module ==

<div class="docs-alert-info">
We added this module in WHMCS 7.9.
</div>

The Stripe SEPA payment gateway module is available in WHMCS.
{{gateways
| type = token
| recurring = yes
| onetime = yes
| refunds = yes
| deletecc = yes
}}
== Adding the Stripe SEPA Payment Gateway ==

To set up the Stripe SEPA 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 '''Stripe SEPA'''.
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
# Enter your Stripe credentials.
#* If you currently also use the [[Stripe]] payment gateway, you can check '''Use Stripe Configuration''' to use your existing API keys.
#* You can find your credentials in [https://dashboard.stripe.com/account/apikeys the Stripe portal].
#* Do not enter a value for the Webhook Secret Key. The system will generate it automatically.
#** The Stripe SEPA module requires a valid Webhook and Secret Key in order for payments to be recognised and automatically applied to invoices.
#** If you modify the secret key for the webhook at Stripe, you must also update it in WHMCS.
#* Do not enter a value for '''Webhook Endpoint Secret'''.
# Click '''Save Changes'''.

=== Test Mode ===

This module does not support test mode.

== Transaction Fees ==

Stripe returns transaction fees in the default currency of the Stripe account. If you have a different default currency in WHMCS, you must ensure you have configured the currency of your Stripe account in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, ''Setup > Payments > Currencies'' along with a valid exchange rate to allow WHMCS to be able to convert the fee into your other currencies.</div>

== Supported Currencies ==

Stripe SEPA '''only''' supports the EUR currency. For other currencies, the Stripe SEPA option won't appear when placing orders or paying invoices.

==Payment Workflow==

This module supports automated recurring and on-demand billing.

SEPA Direct Debit is a pull-based, reusable, and asynchronous payment method. This means that it can take up to 14 business days to confirm the success or failure of a payment after you initiate a debit from the customer’s account, though the average is five business days.. The invoice will be placed in Payment Pending until the payment has cleared.

When making a 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 Stripe/Plaid and is never stored in your local WHMCS installation.

The Stripe API is used for refunds and obtaining transaction information.

==Troubleshooting==

''N/A''

{{modules}}

AsiaPay

2023-02-07T13:46:47Z

Lawrence: /* Troubleshooting */

== 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).

=== 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}}

Downloads

2022-12-13T13:24:48Z

Lawrence: /* Add a Download */

You can offer downloads for your users. This could be anything from product user manuals, relevant software utilities or even the actual products being sold. They can either be hosted locally or remotely.

You can access this feature at '''Support > Downloads'''.

== Add Downloads ==

To offer downloads, you must first create categories. Then, you can add the individual download files.

=== Add a Category ===

To add a category:

# Use the list of categories to navigate to the desired parent category.
# Select the '''Add Category''' tab.
# Enter a name to display.
# Optionally, check '''Hide''' to make this category invisible. If you do this, the category will be available only via direct links.
# Enter a description.
# Click '''Add Category'''.

=== Add a Download ===

To add a download:

# Use the list of categories to navigate to the desired category.
# Select the '''Add Download''' tab.
# Select a file type.
# Enter the title and description.
# In the '''Upload File''' section, select the location of the file:
#* For remotely-hosted files, choose '''Manual FTP Upload to Downloads Folder''' and enter the full URL to the file, including <tt>http://</tt>.
#* For locally-hosted files that exist in the specified '''Downloads''' location at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Storage Settings]]''' or, prior to WHMCS 8.0, '''Setup > Storage Settings''', enter the filename.
#* For large files, we recommend uploading via FTP and choosing '''Manual FTP Upload to Downloads Folder'''.
#* For small files, we recommend uploading by clicking '''Upload File'''. This will upload the file to the <tt>downloads</tt> directory.
# To only offer this download to authenticated clients, check '''Clients Only'''.
# To only offer this download after a purchase, check '''Product Download'''. For more information, see [[Product Downloads Distribution]].
# To hide this download in the Client Area, check '''Hidden'''.
# Click '''Add Download'''.

== Edit Downloads ==

To edit an existing download, use the list of categories to navigate to the desired category and then click on the download name.

Enom

2022-11-15T14:30:32Z

Lawrence: /* User not permitted from this IP address */

== About this Module ==

The Enom module allows you to register and manage domains with Enom.
{{registrar
| register = yes
| transfer = yes
| renew = yes
| lock = yes
| dns = yes
| whois = yes
| getepp = yes
| regns = yes
| dnsmanagement = yes
| emailforwarding = yes
| domainsync = yes
| premium = yes
| transferout = yes
| tldpricingsync = yes
}}

==Activation==

<div class="docs-alert-success">
You must create an [https://www.whmcs.com/partners/enom/ Enom account].
</div>

To activate and begin using the Enom registrar module:

# Log in to your account on the [https://www.enom.com/apitokens/default.aspx Enom website].
# Enter an identifying name in the textbox (for example, <tt>WHMCS</tt>).
# Click '''Generate New API Token'''.
# Copy the generated API token.
# 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 '''Enom''' in the list.
# Click '''Activate'''.
# Enter your Enom username.
# Paste in the API token.
# Check '''Disable IRTP''' to prevent WHMCS from displaying contact information verification notices.
# Check '''Use Default Nameservers''' to use Enom's default nameservers for new registrations, overriding the nameservers in WHMCS.
# Click '''Save Changes'''.
# In your Enom account, go to '''Resellers > Manage > API''' and add your server's IP address.
#* You can find this address in WHMCS at '''Help > [[License Information]]'''.
#* If you do not do this, you will see a '''Registrar Error Invalid Client IP''' error.

<html><a href="http://www.youtube.com/watch?v=0Sz9mkBzLN0&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>
<div class="docs-alert-warning">Before you can begin using the Enom API with your account. you must authorize your server IP address for access to your account. See below for steps to do this.</div>

=== 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.

Before you enable '''Test Mode''' in WHMCS, you must register on Enom's Reseller Test environment:

# Log in to [https://resellertest.enom.com/resellers/reseller-testaccount.aspx Enom's Reseller Test Account].
# Click all three links under '''Test Interface Options''' to configure the test account.
# [https://resellertest.enom.com/apitokens/default.aspx Generate a test API token.]

When you place domain registration orders in WHMCS with test mode active, the domains will appear on your demo Enom account (<tt>http://resellertest.enom.com</tt>) but no domain will actually be registered and you will not be charged.

=== .ca Registrations ===

<tt>.ca</tt> registrations require additional fields. The <tt>Invalid registrant information</tt> error is due to problems with the location field.

Instead of entering the full place name, use one of the following province abbreviations:

* Alberta — <tt>AB</tt>
* British Columbia — <tt>BC</tt>
* Manitoba — <tt>MB</tt>
* New Brunswick — <tt>NB</tt>
* Newfoundland and Labrador — <tt>NL</tt>
* Northwest Territories — <tt>NT</tt>
* Nova Scotia — <tt>NS</tt>
* Nunavut — <tt>NU</tt>
* Ontario — <tt>ON</tt>
* Prince Edward Island — <tt>PE</tt>
* Quebec — <tt>QC</tt>
* Saskatchewan — <tt>SK</tt>
* Yukon — <tt>YT</tt>

== Transfer Pricing ==

Enom does not allow a domain's registration term to be defined when transferring a domain name.

When configuring pricing for TLDs to transfer using Enom, only configure a one year transfer price. Set all other transfer prices to <tt>-1.00</tt>.

== 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 ==

=== User not permitted from this IP address ===

This error message indicates that you haven't yet allowed your server's IP to [[#Activation|access your Enom account via the API]] as described in step 14 above. This must be done via the Enom website before you can use the integration.

The IP you need to authorize is typically the main shared IP of the server, usually most easily found from the IP your WHMCS license is assigned to, but if you're unsure or neither of those IPs work, then Enom can assist and advise you of the IP they see your connection tests as coming from via a support ticket.

=== Cannot parse empty response from server/Empty data response from server - Please try again later ===

This can occur only if an empty response is received from Enom. This isn't a curl error, but an empty response from the Enom API. This suggests a temporary problem at Enom's end. Trying the command again later should be successful.

=== Invalid data response from server - Please try again later ===

This can occur when an unexpected response occurs; e.g. a 404 error or other non-XML method. This suggests a temporary problem at Enom's end. Trying the command again later should be successful.

=== CURL Error ===

A standard curl error which indicates a connection issue between your server and Enom's API. Make certain that your server is able to make cURL calls to the following URLs:

Demo Mode: <tt>resellertest.enom.com</tt>
Live Mode: <tt>reseller.enom.com</tt>

=== Domain name not found ===

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

{{modules}}

Enom

2022-11-15T14:29:20Z

Lawrence: /* User not permitted from this IP address */

== About this Module ==

The Enom module allows you to register and manage domains with Enom.
{{registrar
| register = yes
| transfer = yes
| renew = yes
| lock = yes
| dns = yes
| whois = yes
| getepp = yes
| regns = yes
| dnsmanagement = yes
| emailforwarding = yes
| domainsync = yes
| premium = yes
| transferout = yes
| tldpricingsync = yes
}}

==Activation==

<div class="docs-alert-success">
You must create an [https://www.whmcs.com/partners/enom/ Enom account].
</div>

To activate and begin using the Enom registrar module:

# Log in to your account on the [https://www.enom.com/apitokens/default.aspx Enom website].
# Enter an identifying name in the textbox (for example, <tt>WHMCS</tt>).
# Click '''Generate New API Token'''.
# Copy the generated API token.
# 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 '''Enom''' in the list.
# Click '''Activate'''.
# Enter your Enom username.
# Paste in the API token.
# Check '''Disable IRTP''' to prevent WHMCS from displaying contact information verification notices.
# Check '''Use Default Nameservers''' to use Enom's default nameservers for new registrations, overriding the nameservers in WHMCS.
# Click '''Save Changes'''.
# In your Enom account, go to '''Resellers > Manage > API''' and add your server's IP address.
#* You can find this address in WHMCS at '''Help > [[License Information]]'''.
#* If you do not do this, you will see a '''Registrar Error Invalid Client IP''' error.

<html><a href="http://www.youtube.com/watch?v=0Sz9mkBzLN0&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>
<div class="docs-alert-warning">Before you can begin using the Enom API with your account. you must authorize your server IP address for access to your account. See below for steps to do this.</div>

=== 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.

Before you enable '''Test Mode''' in WHMCS, you must register on Enom's Reseller Test environment:

# Log in to [https://resellertest.enom.com/resellers/reseller-testaccount.aspx Enom's Reseller Test Account].
# Click all three links under '''Test Interface Options''' to configure the test account.
# [https://resellertest.enom.com/apitokens/default.aspx Generate a test API token.]

When you place domain registration orders in WHMCS with test mode active, the domains will appear on your demo Enom account (<tt>http://resellertest.enom.com</tt>) but no domain will actually be registered and you will not be charged.

=== .ca Registrations ===

<tt>.ca</tt> registrations require additional fields. The <tt>Invalid registrant information</tt> error is due to problems with the location field.

Instead of entering the full place name, use one of the following province abbreviations:

* Alberta — <tt>AB</tt>
* British Columbia — <tt>BC</tt>
* Manitoba — <tt>MB</tt>
* New Brunswick — <tt>NB</tt>
* Newfoundland and Labrador — <tt>NL</tt>
* Northwest Territories — <tt>NT</tt>
* Nova Scotia — <tt>NS</tt>
* Nunavut — <tt>NU</tt>
* Ontario — <tt>ON</tt>
* Prince Edward Island — <tt>PE</tt>
* Quebec — <tt>QC</tt>
* Saskatchewan — <tt>SK</tt>
* Yukon — <tt>YT</tt>

== Transfer Pricing ==

Enom does not allow a domain's registration term to be defined when transferring a domain name.

When configuring pricing for TLDs to transfer using Enom, only configure a one year transfer price. Set all other transfer prices to <tt>-1.00</tt>.

== 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 ==

=== User not permitted from this IP address ===

This error message indicates that you haven't yet allowed your server's IP to [[#Activation)|access your Enom account via the API]] as described in step 14 above. This must be done via the Enom website before you can use the integration.

The IP you need to authorize is typically the main shared IP of the server, usually most easily found from the IP your WHMCS license is assigned to, but if you're unsure or neither of those IPs work, then Enom can assist and advise you of the IP they see your connection tests as coming from via a support ticket.

=== Cannot parse empty response from server/Empty data response from server - Please try again later ===

This can occur only if an empty response is received from Enom. This isn't a curl error, but an empty response from the Enom API. This suggests a temporary problem at Enom's end. Trying the command again later should be successful.

=== Invalid data response from server - Please try again later ===

This can occur when an unexpected response occurs; e.g. a 404 error or other non-XML method. This suggests a temporary problem at Enom's end. Trying the command again later should be successful.

=== CURL Error ===

A standard curl error which indicates a connection issue between your server and Enom's API. Make certain that your server is able to make cURL calls to the following URLs:

Demo Mode: <tt>resellertest.enom.com</tt>
Live Mode: <tt>reseller.enom.com</tt>

=== Domain name not found ===

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

{{modules}}

Enom

2022-11-15T14:28:38Z

Lawrence: /* User not permitted from this IP address */

== About this Module ==

The Enom module allows you to register and manage domains with Enom.
{{registrar
| register = yes
| transfer = yes
| renew = yes
| lock = yes
| dns = yes
| whois = yes
| getepp = yes
| regns = yes
| dnsmanagement = yes
| emailforwarding = yes
| domainsync = yes
| premium = yes
| transferout = yes
| tldpricingsync = yes
}}

==Activation==

<div class="docs-alert-success">
You must create an [https://www.whmcs.com/partners/enom/ Enom account].
</div>

To activate and begin using the Enom registrar module:

# Log in to your account on the [https://www.enom.com/apitokens/default.aspx Enom website].
# Enter an identifying name in the textbox (for example, <tt>WHMCS</tt>).
# Click '''Generate New API Token'''.
# Copy the generated API token.
# 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 '''Enom''' in the list.
# Click '''Activate'''.
# Enter your Enom username.
# Paste in the API token.
# Check '''Disable IRTP''' to prevent WHMCS from displaying contact information verification notices.
# Check '''Use Default Nameservers''' to use Enom's default nameservers for new registrations, overriding the nameservers in WHMCS.
# Click '''Save Changes'''.
# In your Enom account, go to '''Resellers > Manage > API''' and add your server's IP address.
#* You can find this address in WHMCS at '''Help > [[License Information]]'''.
#* If you do not do this, you will see a '''Registrar Error Invalid Client IP''' error.

<html><a href="http://www.youtube.com/watch?v=0Sz9mkBzLN0&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>
<div class="docs-alert-warning">Before you can begin using the Enom API with your account. you must authorize your server IP address for access to your account. See below for steps to do this.</div>

=== 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.

Before you enable '''Test Mode''' in WHMCS, you must register on Enom's Reseller Test environment:

# Log in to [https://resellertest.enom.com/resellers/reseller-testaccount.aspx Enom's Reseller Test Account].
# Click all three links under '''Test Interface Options''' to configure the test account.
# [https://resellertest.enom.com/apitokens/default.aspx Generate a test API token.]

When you place domain registration orders in WHMCS with test mode active, the domains will appear on your demo Enom account (<tt>http://resellertest.enom.com</tt>) but no domain will actually be registered and you will not be charged.

=== .ca Registrations ===

<tt>.ca</tt> registrations require additional fields. The <tt>Invalid registrant information</tt> error is due to problems with the location field.

Instead of entering the full place name, use one of the following province abbreviations:

* Alberta — <tt>AB</tt>
* British Columbia — <tt>BC</tt>
* Manitoba — <tt>MB</tt>
* New Brunswick — <tt>NB</tt>
* Newfoundland and Labrador — <tt>NL</tt>
* Northwest Territories — <tt>NT</tt>
* Nova Scotia — <tt>NS</tt>
* Nunavut — <tt>NU</tt>
* Ontario — <tt>ON</tt>
* Prince Edward Island — <tt>PE</tt>
* Quebec — <tt>QC</tt>
* Saskatchewan — <tt>SK</tt>
* Yukon — <tt>YT</tt>

== Transfer Pricing ==

Enom does not allow a domain's registration term to be defined when transferring a domain name.

When configuring pricing for TLDs to transfer using Enom, only configure a one year transfer price. Set all other transfer prices to <tt>-1.00</tt>.

== 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 ==

=== User not permitted from this IP address ===

This error message indicates that you haven't yet allowed your server's IP to [[Enom#Activation)|access your Enom account via the API]] as described in step 14 above. This must be done via the Enom website before you can use the integration.

The IP you need to authorize is typically the main shared IP of the server, usually most easily found from the IP your WHMCS license is assigned to, but if you're unsure or neither of those IPs work, then Enom can assist and advise you of the IP they see your connection tests as coming from via a support ticket.

=== Cannot parse empty response from server/Empty data response from server - Please try again later ===

This can occur only if an empty response is received from Enom. This isn't a curl error, but an empty response from the Enom API. This suggests a temporary problem at Enom's end. Trying the command again later should be successful.

=== Invalid data response from server - Please try again later ===

This can occur when an unexpected response occurs; e.g. a 404 error or other non-XML method. This suggests a temporary problem at Enom's end. Trying the command again later should be successful.

=== CURL Error ===

A standard curl error which indicates a connection issue between your server and Enom's API. Make certain that your server is able to make cURL calls to the following URLs:

Demo Mode: <tt>resellertest.enom.com</tt>
Live Mode: <tt>reseller.enom.com</tt>

=== Domain name not found ===

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

{{modules}}

Enom

2022-11-15T14:28:10Z

Lawrence: /* User not permitted from this IP address */

== About this Module ==

The Enom module allows you to register and manage domains with Enom.
{{registrar
| register = yes
| transfer = yes
| renew = yes
| lock = yes
| dns = yes
| whois = yes
| getepp = yes
| regns = yes
| dnsmanagement = yes
| emailforwarding = yes
| domainsync = yes
| premium = yes
| transferout = yes
| tldpricingsync = yes
}}

==Activation==

<div class="docs-alert-success">
You must create an [https://www.whmcs.com/partners/enom/ Enom account].
</div>

To activate and begin using the Enom registrar module:

# Log in to your account on the [https://www.enom.com/apitokens/default.aspx Enom website].
# Enter an identifying name in the textbox (for example, <tt>WHMCS</tt>).
# Click '''Generate New API Token'''.
# Copy the generated API token.
# 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 '''Enom''' in the list.
# Click '''Activate'''.
# Enter your Enom username.
# Paste in the API token.
# Check '''Disable IRTP''' to prevent WHMCS from displaying contact information verification notices.
# Check '''Use Default Nameservers''' to use Enom's default nameservers for new registrations, overriding the nameservers in WHMCS.
# Click '''Save Changes'''.
# In your Enom account, go to '''Resellers > Manage > API''' and add your server's IP address.
#* You can find this address in WHMCS at '''Help > [[License Information]]'''.
#* If you do not do this, you will see a '''Registrar Error Invalid Client IP''' error.

<html><a href="http://www.youtube.com/watch?v=0Sz9mkBzLN0&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>
<div class="docs-alert-warning">Before you can begin using the Enom API with your account. you must authorize your server IP address for access to your account. See below for steps to do this.</div>

=== 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.

Before you enable '''Test Mode''' in WHMCS, you must register on Enom's Reseller Test environment:

# Log in to [https://resellertest.enom.com/resellers/reseller-testaccount.aspx Enom's Reseller Test Account].
# Click all three links under '''Test Interface Options''' to configure the test account.
# [https://resellertest.enom.com/apitokens/default.aspx Generate a test API token.]

When you place domain registration orders in WHMCS with test mode active, the domains will appear on your demo Enom account (<tt>http://resellertest.enom.com</tt>) but no domain will actually be registered and you will not be charged.

=== .ca Registrations ===

<tt>.ca</tt> registrations require additional fields. The <tt>Invalid registrant information</tt> error is due to problems with the location field.

Instead of entering the full place name, use one of the following province abbreviations:

* Alberta — <tt>AB</tt>
* British Columbia — <tt>BC</tt>
* Manitoba — <tt>MB</tt>
* New Brunswick — <tt>NB</tt>
* Newfoundland and Labrador — <tt>NL</tt>
* Northwest Territories — <tt>NT</tt>
* Nova Scotia — <tt>NS</tt>
* Nunavut — <tt>NU</tt>
* Ontario — <tt>ON</tt>
* Prince Edward Island — <tt>PE</tt>
* Quebec — <tt>QC</tt>
* Saskatchewan — <tt>SK</tt>
* Yukon — <tt>YT</tt>

== Transfer Pricing ==

Enom does not allow a domain's registration term to be defined when transferring a domain name.

When configuring pricing for TLDs to transfer using Enom, only configure a one year transfer price. Set all other transfer prices to <tt>-1.00</tt>.

== 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 ==

=== User not permitted from this IP address ===

This error message indicates that you haven't yet allowed your server's IP to [[Enom#Activation)|access your Enom account via the API as described in step 14 above]]. This must be done via the Enom website before you can use the integration.

The IP you need to authorize is typically the main shared IP of the server, usually most easily found from the IP your WHMCS license is assigned to, but if you're unsure or neither of those IPs work, then Enom can assist and advise you of the IP they see your connection tests as coming from via a support ticket.

=== Cannot parse empty response from server/Empty data response from server - Please try again later ===

This can occur only if an empty response is received from Enom. This isn't a curl error, but an empty response from the Enom API. This suggests a temporary problem at Enom's end. Trying the command again later should be successful.

=== Invalid data response from server - Please try again later ===

This can occur when an unexpected response occurs; e.g. a 404 error or other non-XML method. This suggests a temporary problem at Enom's end. Trying the command again later should be successful.

=== CURL Error ===

A standard curl error which indicates a connection issue between your server and Enom's API. Make certain that your server is able to make cURL calls to the following URLs:

Demo Mode: <tt>resellertest.enom.com</tt>
Live Mode: <tt>reseller.enom.com</tt>

=== Domain name not found ===

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

{{modules}}

Tax Configuration

2022-11-01T14:17:44Z

Lawrence: /* Tax Calculation Mode */

<div class="docs-alert-info"><i class="fa fa-question-circle"></i>For this feature in WHMCS 7.6 and earlier, [https://docs.whmcs.com/index.php?title=Tax/VAT&redirect=no click here].</div>

WHMCS can gather necessary taxes when you make sales.

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

==Enabling Tax Support==

In order to charge tax:

# Enable '''Tax Support'''.
# Click '''Save Changes'''.
# Set the desired settings below.
# Click '''Save Changes''' again.

==General Tax Settings==

===Tax/VAT ID Number===
Enter your company Tax/VAT ID in this field. Invoices will display this under the company address in the client area and on PDF printable invoices.

===Inclusive/Exclusive Tax===

By default, tax is exclusive. You need to add tax onto the prices you enter in WHMCS at the rate you entered. The alternative is inclusive tax, in which the prices you enter in WHMCS already include tax. For inclusive tax, WHMCS needs to work backwards to calculate the amount of tax to charge based on the rates you've set.

*'''Exclusive Tax''' > Tax Amount = Item Price x ( Tax Rate / 100 )
*'''Inclusive Tax''' > Tax Amount = ( Item Price / ( 100 + Tax Rate ) ) x Tax Rate

==Custom Invoice Numbering==

<div class="docs-alert-info">Custom Invoice Number is part of the EU VAT Addon.</div>

To enable Custom Invoice Numbering, toggle the appropriate switch on '''Tax Configuration''' and click '''Save Changes'''. After you enable it, the configured custom invoice numbering will apply to invoices that you generate from then on.

===Custom Invoice Numbering Format===

This is the format of the custom invoice number to apply to the invoices WHMCS generates. The default value of this is <tt>{NUMBER}</tt>, which will contain only the value from '''Next Invoice Number'''.
The field can contain any text in the invoice number that the client will see. You can add more tags to the field, which the system will replace when it generates the invoice.

Available tags are:
* <tt>{NUMBER}</tt> — The value for '''Next Invoice Number'''.
* <tt>{YEAR}</tt> — The four-digit year value for the current date.
* <tt>{MONTH}</tt> — The two-digit month value for the current date.
* <tt>{DAY}</tt> — The two-digit day value for the current date.

===Next Invoice Number===

The number that the system will assign to the next invoice it generates.

<div class="docs-alert-info">Only fill in this field if you want to change the number of the next invoice. Only increase this number; do not decrease it.</div>

===Auto Reset Numbering===
This allows you to automatically reset the invoice number periodically. The automatic invoice numbering reset occurs when the automation cron runs on the last day of the month or year. If you want to use this feature, we recommend that you configure the cron job to run late at night in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''.

==VAT Settings==

===VAT Mode===

Toggle '''VAT Mode''' to ''ON''. This will automatically display a window allowing you to set your VAT label display name. Enter one and then click '''Create Rules'''.

====Auto Configure VAT Tax Rules====

If you accidentally delete a rule or need to recreate or change the name of a rule, click here. Follow the prompts, using the appropriate VAT Rate for each EU country.

===Custom Field Migration===

If a WHMCS installation previously used the EU VAT Addon and a custom field to contain the client VAT Number, this option will display to perform a migration of the tax numbers from the custom field to store them in the client table.

===VAT Number Validation===

Toggle this to ''ON'' to enable validation of VAT numbers during registration and checkout. WHMCS uses VIES to validate EU VAT numbers and HMRC to validate UK VAT numbers.

===Auto Tax Exempt===

Check this to set clients as tax exempt when their VAT number successfully validates.

===Your Home Country===

Select the country for your main business location.

===Home Country Exclusion===

Check this to always charge VAT if the customer's billing address is in the country you selected above.

===Proforma Invoicing/Sequential Paid Invoice Numbering===

Toggle this to ''ON'' to enable the invoice numbering format you set below.

===Sequential Invoice Number Format===

Enter a format for invoice numbering. You can include these tags, which will be replaced with the corresponding information when the invoice is generated:

* <tt>{YEAR}</tt> — The current year.
* <tt>{MONTH}</tt> — The current month.
* <tt>{DAY}</tt> — The current day.
* <tt>{NUMBER}</tt> — The sequential invoice number.

===Next Paid Invoice Number===

Enter a number to use to number the next invoice that WHMCS generates.

===Auto Reset Numbering===

Select the frequency with which WHMCS should automatically reset invoice numbering. Select ''Never'' if you do not want to automatically reset numbering.

===Set Invoice Date on Payment===

Check this to set the invoice date to the current date when payment is applied.

==Tax Rules==

You must configure tax rules in order to automatically charge tax in the cart. You can view and add tax rules in the '''Tax Rules''' tab.

===Adding a Rule===

To add a rule:

* For '''Name''', enter a name for the tax zone, which allows you to identify it.
* For '''Country''', choose whether this tax rate applies to all countries or only applies to a selected country.
* For the state, choose whether it applies to all states in the selected country or only a selected state.
* Finally, enter the tax rate as a percentage (for example, <tt>17.5</tt>).
* Click '''Add Rule'''. The system will create the tax rule and automatically add it to the appropriate table for Level 1 or Level 2 rules.

For example, a UK business would set up the system to charge VAT. In the country field, you would choose '''United Kingdom''' and for the state you would choose '''Apply Rule to All States'''. You would then enter the tax rate of '''20.0''' and click '''Add Rule'''. You can set up an unlimited number of tax rules.

===Changing Tax Rates===

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

For more information, see [[Changing Tax Rates on Existing Invoices]].

===Supported Values===

WHMCS 8.0 and later supports tax rates with up to three decimal places and currency values up to 99 trillion.

[[File:TaxDecimals.png|500px|thumb|center|Tax Rates]]

Prior to WHMCS 8.0, WHMCS only supported tax rates with up to two decimal places.

==Advanced Rules==

===Setting Taxed Items===

The flexible tax system in WHMCS allows you to set, individually, which items apply for tax. WHMCS sets products as untaxed by default. Even if you have tax rules set up, the system won't charge tax for it. This allows you to, for example, charge tax on the products you offer but not on services.

====Setting a Product/Service as Taxable====

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'''.
#Click the edit icon next to the product you wish to set to be taxable.
#Check the checkbox next to the item labelled '''Tax Product'''.
#Save your changes to the product.

====Setting Domains as Taxable====

You can set whether to apply taxes to domains.

====Setting Billable Items as Taxable====

You can set whether to apply tax to billable items.

====Setting Late Fees as Taxable====

You can set whether to apply tax to late fees on invoices.

====Setting Custom Invoices as Taxable====

You can set whether to apply tax to custom (manually created) invoices.

===Compound Tax===

The system calculates compound tax after and on top of a primary tax. If you need to add the Level 2 tax to the Level 1 tax, toggle this option on the advanced tab.

===Deduct Tax Amount===

If the '''Tax Type''' is ''Inclusive'' and the client's country and state or province selections result in them not meeting any of the configured tax rules, deduct an amount from the order. Base this on the total amount for taxable items on the order and the percentage of tax that would apply to the default country 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'''. It will deduct the percentage that applies to the first applicable Level 1 and Level 2 tax rules.

===Tax Calculation Mode===

The '''Calculation Mode''' setting determines how the system calculates taxes.

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

There are two possible values for this setting:

* '''Calculate individually per line item''' — Selecting this option will calculate taxes on a per line item basis. When you select this, the system will calculate tax for each line item, rounded to 2 decimal places. It will also calculate the total tax using the sum of the tax calculation for each individual line item.
* '''Calculate based on collective sum of the taxable line items''' — Selecting this option will calculate taxes using the sum of the taxable line items on an invoice. When you select this, the system totals the individual taxable line items and calculates tax based on the sum total of those taxable line items.

====Tax Amount Differences====
Due to rounding for tax calculation modes and the calculation amounts, the resulting tax amounts may differ.

=====Calculate Individually per Line Item=====

Example tax calculation for 11 line items at $2.21 each:

<div class="docs-related-pages">
(2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) + (2.21 x 20%) = 4.84
</div>

=====Calculate Based on the Collective Sum of the Taxable Line Items=====

Example tax calculation for 11 line items at $2.21 each:

<div class="docs-related-pages">
(24.31 x 20%) = 4.86
</div>

Common Promotions

2022-11-01T13:41:13Z

Lawrence: /* Time Limited Recurring Promotion */

__TOC__

Certain promotions are particularly common in the hosting industry, such as free trials and free domain names. WHMCS's features offer complete support for these promotions.

==Free Domain Name==

You are able to offer free domains with your packages when purchased with certain payment terms. For example, you might want to offer a free domain when a package is purchased annually.

You can set this up when you edit a product 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'''.

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

==Free Trial==

[[Products_and_Services#Pricing_Tab|Free Trial functionality]] is built into WHMCS. It will automatically terminate an account x days after ordering and send an email to the client.

You can configure this promotion when you:

# Edit a product 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'''.
# Configure a promotion code at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Promotions]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Promotions'''.

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

==Time Limited Recurring Promotion==

You are able to offer a time limited recurring promotion with your packages. You can configure this promotion when you create a promotion code at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Promotions]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Promotions''' with '''Recurring''' enabled and '''Recur For''' set to a specific number of billing cycles.

For example, you might want to offer a 50% off discount for the first 6 months of a monthly service. For that, you would enable '''Recurring''' and set '''Recur For''' to <tt>6</tt>.

For more information, see [[Promotions#Limited_Recurring_Promotions|Limited Recurring Promotions]].

Common Promotions

2022-11-01T13:40:33Z

Lawrence: /* Time Limited Recurring Promotion */

__TOC__

Certain promotions are particularly common in the hosting industry, such as free trials and free domain names. WHMCS's features offer complete support for these promotions.

==Free Domain Name==

You are able to offer free domains with your packages when purchased with certain payment terms. For example, you might want to offer a free domain when a package is purchased annually.

You can set this up when you edit a product 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'''.

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

==Free Trial==

[[Products_and_Services#Pricing_Tab|Free Trial functionality]] is built into WHMCS. It will automatically terminate an account x days after ordering and send an email to the client.

You can configure this promotion when you:

# Edit a product 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'''.
# Configure a promotion code at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Promotions]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Promotions'''.

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

==Time Limited Recurring Promotion==

You are able to offer a time limited recurring promotion with your packages. You can configure this promotion when you create a promotion code at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Promotions]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Promotions''' with '''Recurring''' enabled and '''Recur For''' set to a specific number of billing cycles.

For example, you might want to offer a 50% off discount for the first 6 months of a monthly service. For that, you would enable '''Recurring''' and set '''Recur For''' to <tt>6</tt>.

For more information, see [Promotions#Limited_Recurring_Promotions|Limited Recurring Promotions].

Common Promotions

2022-11-01T13:39:49Z

Lawrence: /* Time Limited Recurring Promotion */

__TOC__

Certain promotions are particularly common in the hosting industry, such as free trials and free domain names. WHMCS's features offer complete support for these promotions.

==Free Domain Name==

You are able to offer free domains with your packages when purchased with certain payment terms. For example, you might want to offer a free domain when a package is purchased annually.

You can set this up when you edit a product 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'''.

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

==Free Trial==

[[Products_and_Services#Pricing_Tab|Free Trial functionality]] is built into WHMCS. It will automatically terminate an account x days after ordering and send an email to the client.

You can configure this promotion when you:

# Edit a product 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'''.
# Configure a promotion code at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Promotions]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Promotions'''.

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

==Time Limited Recurring Promotion==

You are able to offer a time limited recurring promotion with your packages. You can configure this promotion when you create a promotion code at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Promotions]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Promotions''' with '''Recurring''' enabled and '''Recur For''' set to a specific number of billing cycles.

For example, you might want to offer a 50% off discount for the first 6 months of a monthly service. For that, you would enable '''Recurring''' and set '''Recur For''' to <tt>6</tt>.

For more information, see [[Limited_Recurring_Promotions][Promotions#Limited_Recurring_Promotions]].

Common Promotions

2022-11-01T13:38:48Z

Lawrence: /* Time Limited Recurring Promotion */

Common Promotions

2022-11-01T13:37:29Z

Lawrence:

__TOC__

Certain promotions are particularly common in the hosting industry, such as free trials and free domain names. WHMCS's features offer complete support for these promotions.

==Free Domain Name==

You are able to offer free domains with your packages when purchased with certain payment terms. For example, you might want to offer a free domain when a package is purchased annually.

You can set this up when you edit a product 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'''.

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

==Free Trial==

[[Products_and_Services#Pricing_Tab|Free Trial functionality]] is built into WHMCS. It will automatically terminate an account x days after ordering and send an email to the client.

You can configure this promotion when you:

# Edit a product 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'''.
# Configure a promotion code at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Promotions]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Promotions'''.

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

==Time Limited Recurring Promotion==

You are able to offer a time limited recurring promotion with your packages. You can offer this promotion when you configure a promotion code at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Promotions]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Promotions''' with '''Recurring''' enabled and '''Recur For''' set to a specific number of billing cycles.

For example, you might want to offer a 50% off discount for the first 6 months of a monthly service. For that, you would enable '''Recurring''' and set '''Recur For''' to <tt>6</tt>.

For more information, see [[Promotions#Limited_Recurring_Promotions]].

Plesk

2022-10-04T12:21:46Z

Lawrence: /* Overriding Overage Billing Soft Limits with Configurable Options */

== About this Module ==

The Plesk module allows you to add and manage Plesk servers in WHMCS.

<div class="docs-alert-info">
* This module is compatible with Plesk versions 11, 11.5, 12, 12.5, Onyx, and Obsidian.
* You can also [[Plesk Single Sign-On|use single sign-on with Plesk]].
</div>
{{Provisioning_Module
| changepackage = Yes
| changepw = Yes
| usageupdates = Yes
| clientarealink = Yes
| port = 8443}}
== Adding a Plesk Server ==

To set up a Plesk 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 ''Plesk'' from the menu.
# Enter the hostname or IP address.
# Enter a username and password.
# Click '''Test Connection'''.
# Enter the desired additional server details.
# Click '''Save Changes'''.
# If this is the only Plesk 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.

For more information, see [https://help.whmcs.com/m/87388/l/1076210 Creating Your First Plesk Server] and [[Plesk Onyx]].

== Creating a Plesk Product ==

[[File:plesk12_3new.png|thumb|Creating a Plesk Product]]

You can create a product that provisions accounts on your Plesk 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'''.

=== Configurable Options ===

<div class="docs-alert-info">
* If you set up configurable options, you will also use Plesk's Panel Addons. This Plesk feature is '''not''' part of WHMCS's product addon system.
* A friendly name can be assigned to configurable options in order to display a different name to clients. This is sometimes preferable to displaying the system value as it appears inside Plesk. For more information, see [[Addons_and_Configurable_Options#Friendly_Display_Names|Friendly Display Names]].
</div>

[[File:Plesk_addons.png |thumb|Plesk Panel Addons]]
[[File:Plesk_config_opt_setup_8-2.png |thumb|WHMCS Plesk Configurable Options]]
[[File:WHMCS-plesk-extra-bandwidth-8-2.png |thumb|WHMCS Plesk Bandwidth Configurable Options]]

To create configurable options that attach Plesk's Panel Addons to your Plesk products:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Configurable Options]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Configurable Options'''.
# Perform one of the following actions:
#* Click the '''Edit''' icon for an existing group.
#* Click '''Create a New Group''', configure the group name, description, and assigned products, and then click '''Save Changes'''.
# Click '''Add New Configurable Option'''.
# Enter an option name using the <tt>Plesk Panel-Addon-Name</tt> name format, replacing <tt>Panel-Addon-Name</tt> with the exact name that displays in Plesk for that Plesk Panel Addon. For example:
#* In the '''Plesk Panel Addons''' image above, one of the configured Panel Addons is '''Extra Bandwidth''', with resources of <tt>5GB</tt> or <tt>10GB</tt>.
#* In WHMCS in the '''WHMCS Plesk Configurable Options''' image above, this is '''Plesk Extra Bandwidth'''.
#* In the '''WHMCS Plesk Bandwidth Configurable Options''' image above, '''10GB Extra Bandwidth''' and '''5GB Extra Bandwidth''' are set to ensure that the bandwidth options in Plesk and WHMCS match.<div class="docs-alert-info">We recommend that you set the first option to '''None''' or a similar value. When you do this, ensure that the '''Panel Addon''' uses a value of <tt>0</tt>. This gives the user the ability to choose not to have any additional values per option.</div>
# Select ''Yes/No'' or ''Dropdown'' as the '''Option Type''' setting.
# Enter the desired options and display order.
# Click '''Save Changes'''.
# Create each desired additional option.
# Click '''Close Window'''.
# Select the desired products in the '''Assigned Products''' list.
# Click '''Save Changes'''.
# 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'''.
# Edit the desired product or service.
# In the '''Configurable Options''' tab, select the desired options.
# Click '''Save Changes'''.

==== Dedicated IP Address ====

To create configurable options that provision a dedicated IP address, use either or both of these exact names when you create configurable options:

* <tt>Dedicated IPv4</tt>
* <tt>Dedicated IPv6</tt>

Select ''Yes/No'' from the '''Option Type''' menu for these options.

====Overriding Overage Billing Soft Limits with Configurable Options====

When using configurable options to override the soft limits for overage billing on a Plesk product, you must create a <tt>config.ini</tt> file in the <tt>/modules/servers</tt> directory with the following contents:

;WHMCS Plesk Provisioning Module Config File
skip_addon_prefix = true

After you create this file, ensure that you have configured <tt>Disk Space</tt> and <tt>Bandwidth</tt> configurable options using our [[Disk_Space_and_Bandwidth_Overage_Billing#Custom_Fields_and_Configurable_Options|Custom Fields and Configurable Options]] documentation. This will ensure that the overrides function correctly.

=== Add-On Features ===

In WHMCS 8.2 and later, in addition to WHMCS's existing product addon functionality (now an '''Independent Product'''), you can create an '''Add-On Feature'''. These addons let you sell module-specific features like the WordPress Toolkit offerings available through both cPanel & WHM and Plesk.

For more information and steps to create an addon, see [[Product Addons]].

=== Reseller Packages ===

When creating a reseller package, create the service plan on your Plesk server in the '''Reseller Plans''' tab at '''Hosting Services > Service Plans'''.

When you configure the product in WHMCS, use the following settings:

* In the '''Details''' tab, set the '''Product Type''' setting to ''Reseller Account''.
* In the '''Module Settings''' tab, set the '''Service Plan Name''' ''and'' '''Reseller Plan Name''' settings.

Creating a reseller account will '''not''' create a shared hosting space for the reseller's website. After account creation, the reseller can log in to Plesk and set up their own hosting space.

===Metric Billing===

<div class="docs-alert-info"><i class="fa fa-info-circle"></i>We added metric billing for Plesk in WHMCS 8.5.</div>

You can bill clients for their use of individual items like databases or bandwidth. You can choose whether to include a certain amount in the base price and only charge for exceeding a certain limit, offer tiered pricing, or charge for every unit of an item.

You can configure metric billing in the '''Metric Billing''' tab.

When a client orders this product, WHMCS will track the account's use of the items you configured. On the service's '''Next Due Date''', the system will record that period's usage and add the cost to the service's renewal invoice.

For more information, see [[Usage Billing]].

=== Log in to Plesk ===

When you click '''Log in to Plesk''' in the Client Area ''or'' Admin Area, WHMCS bases its actions on the server hostname if it is available. If it is not, WHMCS uses the IP address.

The use of <tt>http</tt> and <tt>https</tt> login links depends on the '''Secure''' setting in your server's configuration.

=== WHMCS Connect ===

WHMCS Connect allows you and your administrators to quickly and easily access the control panels of all the servers configured in your WHMCS installation that support Single Sign-On, enabling you and your staff to administer and make changes without ever needing to re-authenticate.

For more information, see [[WHMCS_Connect]].

== Troubleshooting ==

=== The client account is getting setup but the domain is not ===

This is usually due to the permissions of the domain template exceeding the server resources or containing something unsupported (for example, ColdFusion). Always test whether your domain template works directly in Plesk after setting it up.

=== I get a blank command error from WHMCS when it tries to setup an account ===

This can occur if your firewall is blocking connections on port 8443. You need to open it on both the server WHMCS is on and the server WHMCS is connecting to for inbound and outbound connections.

=== With accounts created on my Plesk server from WHMCS the www. subdomain doesn't work ===

This happens due to the default DNS settings on a Plesk server and the requirement to check a box when creating an account to enable it.

To avoid that, simply follow the steps below.
# Log in to Plesk.
# Click '''Server'''.
# Click '''DNS Settings'''.
# Click '''Add New Record'''.
# Choose '''CNAME''' under the record type.
# Enter <tt>www</tt> in '''Enter Domain Name'''.
# Enter <tt><domain></tt> in '''Enter Canonical Name'''.
# Click '''OK''' to complete the changes.

=== Page not Found/Timeout/502 Bad Gateway error creating accounts ===

By default, Plesk performs a forced restart of Apache when an account is created or suspended. This causes WHMCS to lose connection to the server, and, if WHMCS is on the same server, you will also lose connection to WHMCS.

To resolve this, see [https://support.plesk.com/hc/en-us/articles/213907285 Plesk's support article].

=== 503 Service Temporarily Unavailable error creating accounts ===

By default, Plesk performs a forced restart of Apache when an account is created or suspended. This causes WHMCS to lose connection to the server, and, if WHMCS is on the same server, you will also lose connection to WHMCS.

To resolve this, see [https://support.plesk.com/hc/en-us/articles/115003664213-Unable-to-create-domain-through-WHMCS-503-Service-Temporarily-Unavailable Plesk's support article].

===Unable to create account in Panel. The field 'username' is required.===

This means the username under the client's '''Products/Services''' tab is empty.

Enter a username, save changes, and try module creation again. Then, ensure that '''Require Domains''' is enabled for the product 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'''.

===0 - Unable to find appropriate manager for this version of Panel. Plesk should be at least 8.0 version===

This is a generic error message that the Plesk module returns. For example, it could indicate a connection error or invalid credentials.

To identify the underlying error that is occurring, check the '''Module Log''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' or, prior to WHMCS 8.0, '''Utilities > Logs > Module Log'''. Enable it, reproduce the error, disable it again, and the ''''Response''' column will show the underlying error.

For more information, see [[Troubleshooting_Module_Problems]].

===1006 - Permission denied===

This indicates that your Plesk login doesn't have the necessary permissions to use the API. You need the server administrator to grant your Plesk reseller account the '''Ability to use remote API''' permission.

===1013 - Template does not exist===

This error message is coming directly from the Plesk API and indicates that the client and domain template names are incorrect or missing. You can correct these in the product's '''Module Settings''' tab.

===1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel===

There are two potential causes of this error message:

==== Incorrect product type ====

The product type is set incorrectly in WHMCS (for example, a reseller plan is configured as a shared hosting product in WHMCS).

To resolve this:

# Log in to WHMCS Admin Area.
# Navigate 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'''.
# Set '''Product Type''' to ''Shared Hosting'' or ''Reseller Hosting'' to match the Plesk plan type.
# Click '''Save Changes'''.

==== Missing data from a table inside Plesk ====

If the error persists after following the ''Incorrect product type'' steps above, see [https://support.plesk.com/hc/en-us/articles/213932225-Error-while-accessing-Plesk-from-WHMCS-via-API-Customer-with-external-id-whmcs-plesk-XX-is-not-found-in-panel this article].

===1013 - Error message: Customer with external id 'xxxxxxxx' is not found in panel===

Refer to the solution for [[#1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel|1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel]] above.

===1014 - Parser error: Request is invalid===

This error message indicates there is a field value missing. This is most commonly caused by having no assigned IP addresses in the client or domain template's IP pool.

===1014 - Parser error: Cannot parse the XML from the source specified===

The Plesk API only supports the characters a-z and 0-9. If the client's profile contains accents or other characters, it will cause account creation to fail. Edit the client's profile to remove these characters.

===1018 - Unable to create hosting. IP address does not exist in client's pool===

This error indicates that there is an issue with the IP address pool configuration in Plesk. For example, there may not be any available IP addresses or the first IP address may be set as dedicated instead of shared.

===1023 - Unable to accept the template: the following limitations are exceeded===

This issue occurs when the resources provided by the serivce plan addon were already used by the subscription.

To resolve this:

# In the subscription for that domain name, remove the referenced addon in Plesk.
# In WHMCS, go to the product or service's '''Products/Services''' tab.
# Use the "Upgrade/Downgrade" option to create an upgrade order.

===2306 - Domain adding was failed. Error: xxxxx template failed: Unable to apply limits===

This error message comes direct from the Plesk API. It indicates that the template you are attempting to use exceeds your limits or has a feature your server doesn't support. Create an account with the template inside Plesk to retrieve further details.

===Plesk login requires user authentication===

This issue can happen when the user has a dynamic IP addresses or an unstable internet connection. Selecting '''Allow IP changes during one session''' in Plesk [https://docs.plesk.com/en-US/obsidian/administrator-guide/server-administration/session-preferences.60305/ will resolve this].

{{modules}}

Plesk

2022-10-04T12:21:28Z

Lawrence: /* Configurable Options */

Plesk

2022-10-04T12:20:56Z

Lawrence:

== About this Module ==

The Plesk module allows you to add and manage Plesk servers in WHMCS.

<div class="docs-alert-info">
* This module is compatible with Plesk versions 11, 11.5, 12, 12.5, Onyx, and Obsidian.
* You can also [[Plesk Single Sign-On|use single sign-on with Plesk]].
</div>
{{Provisioning_Module
| changepackage = Yes
| changepw = Yes
| usageupdates = Yes
| clientarealink = Yes
| port = 8443}}
== Adding a Plesk Server ==

To set up a Plesk 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 ''Plesk'' from the menu.
# Enter the hostname or IP address.
# Enter a username and password.
# Click '''Test Connection'''.
# Enter the desired additional server details.
# Click '''Save Changes'''.
# If this is the only Plesk 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.

For more information, see [https://help.whmcs.com/m/87388/l/1076210 Creating Your First Plesk Server] and [[Plesk Onyx]].

== Creating a Plesk Product ==

[[File:plesk12_3new.png|thumb|Creating a Plesk Product]]

You can create a product that provisions accounts on your Plesk 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'''.

=== Configurable Options ===

<div class="docs-alert-info">
* If you set up configurable options, you will also use Plesk's Panel Addons. This Plesk feature is '''not''' part of WHMCS's product addon system.
* A friendly name can be assigned to configurable options in order to display a different name to clients. This is sometimes preferable to displaying the system value as it appears inside Plesk. For more information, see [[Addons_and_Configurable_Options#Friendly_Display_Names|Friendly Display Names]].
</div>

[[File:Plesk_addons.png |thumb|Plesk Panel Addons]]
[[File:Plesk_config_opt_setup_8-2.png |thumb|WHMCS Plesk Configurable Options]]
[[File:WHMCS-plesk-extra-bandwidth-8-2.png |thumb|WHMCS Plesk Bandwidth Configurable Options]]

To create configurable options that attach Plesk's Panel Addons to your Plesk products:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Configurable Options]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Configurable Options'''.
# Perform one of the following actions:
#* Click the '''Edit''' icon for an existing group.
#* Click '''Create a New Group''', configure the group name, description, and assigned products, and then click '''Save Changes'''.
# Click '''Add New Configurable Option'''.
# Enter an option name using the <tt>Plesk Panel-Addon-Name</tt> name format, replacing <tt>Panel-Addon-Name</tt> with the exact name that displays in Plesk for that Plesk Panel Addon. For example:
#* In the '''Plesk Panel Addons''' image above, one of the configured Panel Addons is '''Extra Bandwidth''', with resources of <tt>5GB</tt> or <tt>10GB</tt>.
#* In WHMCS in the '''WHMCS Plesk Configurable Options''' image above, this is '''Plesk Extra Bandwidth'''.
#* In the '''WHMCS Plesk Bandwidth Configurable Options''' image above, '''10GB Extra Bandwidth''' and '''5GB Extra Bandwidth''' are set to ensure that the bandwidth options in Plesk and WHMCS match.<div class="docs-alert-info">We recommend that you set the first option to '''None''' or a similar value. When you do this, ensure that the '''Panel Addon''' uses a value of <tt>0</tt>. This gives the user the ability to choose not to have any additional values per option.</div>
# Select ''Yes/No'' or ''Dropdown'' as the '''Option Type''' setting.
# Enter the desired options and display order.
# Click '''Save Changes'''.
# Create each desired additional option.
# Click '''Close Window'''.
# Select the desired products in the '''Assigned Products''' list.
# Click '''Save Changes'''.
# 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'''.
# Edit the desired product or service.
# In the '''Configurable Options''' tab, select the desired options.
# Click '''Save Changes'''.

==== Dedicated IP Address ====

To create configurable options that provision a dedicated IP address, use either or both of these exact names when you create configurable options:

* <tt>Dedicated IPv4</tt>
* <tt>Dedicated IPv6</tt>

Select ''Yes/No'' from the '''Option Type''' menu for these options.

=== Add-On Features ===

In WHMCS 8.2 and later, in addition to WHMCS's existing product addon functionality (now an '''Independent Product'''), you can create an '''Add-On Feature'''. These addons let you sell module-specific features like the WordPress Toolkit offerings available through both cPanel & WHM and Plesk.

For more information and steps to create an addon, see [[Product Addons]].

=== Reseller Packages ===

When creating a reseller package, create the service plan on your Plesk server in the '''Reseller Plans''' tab at '''Hosting Services > Service Plans'''.

When you configure the product in WHMCS, use the following settings:

* In the '''Details''' tab, set the '''Product Type''' setting to ''Reseller Account''.
* In the '''Module Settings''' tab, set the '''Service Plan Name''' ''and'' '''Reseller Plan Name''' settings.

Creating a reseller account will '''not''' create a shared hosting space for the reseller's website. After account creation, the reseller can log in to Plesk and set up their own hosting space.

===Metric Billing===

<div class="docs-alert-info"><i class="fa fa-info-circle"></i>We added metric billing for Plesk in WHMCS 8.5.</div>

You can bill clients for their use of individual items like databases or bandwidth. You can choose whether to include a certain amount in the base price and only charge for exceeding a certain limit, offer tiered pricing, or charge for every unit of an item.

You can configure metric billing in the '''Metric Billing''' tab.

When a client orders this product, WHMCS will track the account's use of the items you configured. On the service's '''Next Due Date''', the system will record that period's usage and add the cost to the service's renewal invoice.

For more information, see [[Usage Billing]].

=== Log in to Plesk ===

When you click '''Log in to Plesk''' in the Client Area ''or'' Admin Area, WHMCS bases its actions on the server hostname if it is available. If it is not, WHMCS uses the IP address.

The use of <tt>http</tt> and <tt>https</tt> login links depends on the '''Secure''' setting in your server's configuration.

=== WHMCS Connect ===

WHMCS Connect allows you and your administrators to quickly and easily access the control panels of all the servers configured in your WHMCS installation that support Single Sign-On, enabling you and your staff to administer and make changes without ever needing to re-authenticate.

For more information, see [[WHMCS_Connect]].

== Troubleshooting ==

=== The client account is getting setup but the domain is not ===

This is usually due to the permissions of the domain template exceeding the server resources or containing something unsupported (for example, ColdFusion). Always test whether your domain template works directly in Plesk after setting it up.

=== I get a blank command error from WHMCS when it tries to setup an account ===

This can occur if your firewall is blocking connections on port 8443. You need to open it on both the server WHMCS is on and the server WHMCS is connecting to for inbound and outbound connections.

=== With accounts created on my Plesk server from WHMCS the www. subdomain doesn't work ===

This happens due to the default DNS settings on a Plesk server and the requirement to check a box when creating an account to enable it.

To avoid that, simply follow the steps below.
# Log in to Plesk.
# Click '''Server'''.
# Click '''DNS Settings'''.
# Click '''Add New Record'''.
# Choose '''CNAME''' under the record type.
# Enter <tt>www</tt> in '''Enter Domain Name'''.
# Enter <tt><domain></tt> in '''Enter Canonical Name'''.
# Click '''OK''' to complete the changes.

=== Page not Found/Timeout/502 Bad Gateway error creating accounts ===

By default, Plesk performs a forced restart of Apache when an account is created or suspended. This causes WHMCS to lose connection to the server, and, if WHMCS is on the same server, you will also lose connection to WHMCS.

To resolve this, see [https://support.plesk.com/hc/en-us/articles/213907285 Plesk's support article].

=== 503 Service Temporarily Unavailable error creating accounts ===

By default, Plesk performs a forced restart of Apache when an account is created or suspended. This causes WHMCS to lose connection to the server, and, if WHMCS is on the same server, you will also lose connection to WHMCS.

To resolve this, see [https://support.plesk.com/hc/en-us/articles/115003664213-Unable-to-create-domain-through-WHMCS-503-Service-Temporarily-Unavailable Plesk's support article].

===Unable to create account in Panel. The field 'username' is required.===

This means the username under the client's '''Products/Services''' tab is empty.

Enter a username, save changes, and try module creation again. Then, ensure that '''Require Domains''' is enabled for the product 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'''.

===0 - Unable to find appropriate manager for this version of Panel. Plesk should be at least 8.0 version===

This is a generic error message that the Plesk module returns. For example, it could indicate a connection error or invalid credentials.

To identify the underlying error that is occurring, check the '''Module Log''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' or, prior to WHMCS 8.0, '''Utilities > Logs > Module Log'''. Enable it, reproduce the error, disable it again, and the ''''Response''' column will show the underlying error.

For more information, see [[Troubleshooting_Module_Problems]].

===1006 - Permission denied===

This indicates that your Plesk login doesn't have the necessary permissions to use the API. You need the server administrator to grant your Plesk reseller account the '''Ability to use remote API''' permission.

===1013 - Template does not exist===

This error message is coming directly from the Plesk API and indicates that the client and domain template names are incorrect or missing. You can correct these in the product's '''Module Settings''' tab.

===1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel===

There are two potential causes of this error message:

==== Incorrect product type ====

The product type is set incorrectly in WHMCS (for example, a reseller plan is configured as a shared hosting product in WHMCS).

To resolve this:

# Log in to WHMCS Admin Area.
# Navigate 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'''.
# Set '''Product Type''' to ''Shared Hosting'' or ''Reseller Hosting'' to match the Plesk plan type.
# Click '''Save Changes'''.

==== Missing data from a table inside Plesk ====

If the error persists after following the ''Incorrect product type'' steps above, see [https://support.plesk.com/hc/en-us/articles/213932225-Error-while-accessing-Plesk-from-WHMCS-via-API-Customer-with-external-id-whmcs-plesk-XX-is-not-found-in-panel this article].

===1013 - Error message: Customer with external id 'xxxxxxxx' is not found in panel===

Refer to the solution for [[#1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel|1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel]] above.

===1014 - Parser error: Request is invalid===

This error message indicates there is a field value missing. This is most commonly caused by having no assigned IP addresses in the client or domain template's IP pool.

===1014 - Parser error: Cannot parse the XML from the source specified===

The Plesk API only supports the characters a-z and 0-9. If the client's profile contains accents or other characters, it will cause account creation to fail. Edit the client's profile to remove these characters.

===1018 - Unable to create hosting. IP address does not exist in client's pool===

This error indicates that there is an issue with the IP address pool configuration in Plesk. For example, there may not be any available IP addresses or the first IP address may be set as dedicated instead of shared.

===1023 - Unable to accept the template: the following limitations are exceeded===

This issue occurs when the resources provided by the serivce plan addon were already used by the subscription.

To resolve this:

# In the subscription for that domain name, remove the referenced addon in Plesk.
# In WHMCS, go to the product or service's '''Products/Services''' tab.
# Use the "Upgrade/Downgrade" option to create an upgrade order.

===2306 - Domain adding was failed. Error: xxxxx template failed: Unable to apply limits===

This error message comes direct from the Plesk API. It indicates that the template you are attempting to use exceeds your limits or has a feature your server doesn't support. Create an account with the template inside Plesk to retrieve further details.

===Plesk login requires user authentication===

This issue can happen when the user has a dynamic IP addresses or an unstable internet connection. Selecting '''Allow IP changes during one session''' in Plesk [https://docs.plesk.com/en-US/obsidian/administrator-guide/server-administration/session-preferences.60305/ will resolve this].

{{modules}}

Plesk

2022-10-04T12:19:55Z

Lawrence:

== About this Module ==

The Plesk module allows you to add and manage Plesk servers in WHMCS.

<div class="docs-alert-info">
* This module is compatible with Plesk versions 11, 11.5, 12, 12.5, Onyx, and Obsidian.
* You can also [[Plesk Single Sign-On|use single sign-on with Plesk]].
</div>
{{Provisioning_Module
| changepackage = Yes
| changepw = Yes
| usageupdates = Yes
| clientarealink = Yes
| port = 8443}}
== Adding a Plesk Server ==

To set up a Plesk 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 ''Plesk'' from the menu.
# Enter the hostname or IP address.
# Enter a username and password.
# Click '''Test Connection'''.
# Enter the desired additional server details.
# Click '''Save Changes'''.
# If this is the only Plesk 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.

For more information, see [https://help.whmcs.com/m/87388/l/1076210 Creating Your First Plesk Server] and [[Plesk Onyx]].

== Creating a Plesk Product ==

[[File:plesk12_3new.png|thumb|Creating a Plesk Product]]

You can create a product that provisions accounts on your Plesk 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'''.

=== Configurable Options ===

<div class="docs-alert-info">
* If you set up configurable options, you will also use Plesk's Panel Addons. This Plesk feature is '''not''' part of WHMCS's product addon system.
* A friendly name can be assigned to configurable options in order to display a different name to clients. This is sometimes preferable to displaying the system value as it appears inside Plesk. For more information, see [[Addons_and_Configurable_Options#Friendly_Display_Names|Friendly Display Names]].
</div>

[[File:Plesk_addons.png |thumb|Plesk Panel Addons]]
[[File:Plesk_config_opt_setup_8-2.png |thumb|WHMCS Plesk Configurable Options]]
[[File:WHMCS-plesk-extra-bandwidth-8-2.png |thumb|WHMCS Plesk Bandwidth Configurable Options]]

To create configurable options that attach Plesk's Panel Addons to your Plesk products:

# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Configurable Options]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Configurable Options'''.
# Perform one of the following actions:
#* Click the '''Edit''' icon for an existing group.
#* Click '''Create a New Group''', configure the group name, description, and assigned products, and then click '''Save Changes'''.
# Click '''Add New Configurable Option'''.
# Enter an option name using the <tt>Plesk Panel-Addon-Name</tt> name format, replacing <tt>Panel-Addon-Name</tt> with the exact name that displays in Plesk for that Plesk Panel Addon. For example:
#* In the '''Plesk Panel Addons''' image above, one of the configured Panel Addons is '''Extra Bandwidth''', with resources of <tt>5GB</tt> or <tt>10GB</tt>.
#* In WHMCS in the '''WHMCS Plesk Configurable Options''' image above, this is '''Plesk Extra Bandwidth'''.
#* In the '''WHMCS Plesk Bandwidth Configurable Options''' image above, '''10GB Extra Bandwidth''' and '''5GB Extra Bandwidth''' are set to ensure that the bandwidth options in Plesk and WHMCS match.<div class="docs-alert-info">We recommend that you set the first option to '''None''' or a similar value. When you do this, ensure that the '''Panel Addon''' uses a value of <tt>0</tt>. This gives the user the ability to choose not to have any additional values per option.</div>
# Select ''Yes/No'' or ''Dropdown'' as the '''Option Type''' setting.
# Enter the desired options and display order.
# Click '''Save Changes'''.
# Create each desired additional option.
# Click '''Close Window'''.
# Select the desired products in the '''Assigned Products''' list.
# Click '''Save Changes'''.
# 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'''.
# Edit the desired product or service.
# In the '''Configurable Options''' tab, select the desired options.
# Click '''Save Changes'''.

==== Dedicated IP Address ====

To create configurable options that provision a dedicated IP address, use either or both of these exact names when you create configurable options:

* <tt>Dedicated IPv4</tt>
* <tt>Dedicated IPv6</tt>

Select ''Yes/No'' from the '''Option Type''' menu for these options.

=== Add-On Features ===

In WHMCS 8.2 and later, in addition to WHMCS's existing product addon functionality (now an '''Independent Product'''), you can create an '''Add-On Feature'''. These addons let you sell module-specific features like the WordPress Toolkit offerings available through both cPanel & WHM and Plesk.

For more information and steps to create an addon, see [[Product Addons]].

=== Reseller Packages ===

When creating a reseller package, create the service plan on your Plesk server in the '''Reseller Plans''' tab at '''Hosting Services > Service Plans'''.

When you configure the product in WHMCS, use the following settings:

* In the '''Details''' tab, set the '''Product Type''' setting to ''Reseller Account''.
* In the '''Module Settings''' tab, set the '''Service Plan Name''' ''and'' '''Reseller Plan Name''' settings.

Creating a reseller account will '''not''' create a shared hosting space for the reseller's website. After account creation, the reseller can log in to Plesk and set up their own hosting space.

===Metric Billing===

<div class="docs-alert-info"><i class="fa fa-info-circle"></i>We added metric billing for Plesk in WHMCS 8.5.</div>

You can bill clients for their use of individual items like databases or bandwidth. You can choose whether to include a certain amount in the base price and only charge for exceeding a certain limit, offer tiered pricing, or charge for every unit of an item.

You can configure metric billing in the '''Metric Billing''' tab.

When a client orders this product, WHMCS will track the account's use of the items you configured. On the service's '''Next Due Date''', the system will record that period's usage and add the cost to the service's renewal invoice.

For more information, see [[Usage Billing]].

===Overriding Overage Billing Soft Limits with Configurable Options===

When using configurable options to override the soft limits for overage billing on a Plesk product, you must create a <tt>config.ini</tt> file in the <tt>/modules/servers</tt> directory with the following contents:

;WHMCS Plesk Provisioning Module Config File
skip_addon_prefix = true

After you create this file, ensure that you have configured <tt>Disk Space</tt> and <tt>Bandwidth</tt> configurable options using our [[Disk_Space_and_Bandwidth_Overage_Billing#Custom_Fields_and_Configurable_Options|Custom Fields and Configurable Options]] documentation. This will ensure that the overrides function correctly.

=== Log in to Plesk ===

When you click '''Log in to Plesk''' in the Client Area ''or'' Admin Area, WHMCS bases its actions on the server hostname if it is available. If it is not, WHMCS uses the IP address.

The use of <tt>http</tt> and <tt>https</tt> login links depends on the '''Secure''' setting in your server's configuration.

=== WHMCS Connect ===

WHMCS Connect allows you and your administrators to quickly and easily access the control panels of all the servers configured in your WHMCS installation that support Single Sign-On, enabling you and your staff to administer and make changes without ever needing to re-authenticate.

For more information, see [[WHMCS_Connect]].

== Troubleshooting ==

=== The client account is getting setup but the domain is not ===

This is usually due to the permissions of the domain template exceeding the server resources or containing something unsupported (for example, ColdFusion). Always test whether your domain template works directly in Plesk after setting it up.

=== I get a blank command error from WHMCS when it tries to setup an account ===

This can occur if your firewall is blocking connections on port 8443. You need to open it on both the server WHMCS is on and the server WHMCS is connecting to for inbound and outbound connections.

=== With accounts created on my Plesk server from WHMCS the www. subdomain doesn't work ===

This happens due to the default DNS settings on a Plesk server and the requirement to check a box when creating an account to enable it.

To avoid that, simply follow the steps below.
# Log in to Plesk.
# Click '''Server'''.
# Click '''DNS Settings'''.
# Click '''Add New Record'''.
# Choose '''CNAME''' under the record type.
# Enter <tt>www</tt> in '''Enter Domain Name'''.
# Enter <tt><domain></tt> in '''Enter Canonical Name'''.
# Click '''OK''' to complete the changes.

=== Page not Found/Timeout/502 Bad Gateway error creating accounts ===

By default, Plesk performs a forced restart of Apache when an account is created or suspended. This causes WHMCS to lose connection to the server, and, if WHMCS is on the same server, you will also lose connection to WHMCS.

To resolve this, see [https://support.plesk.com/hc/en-us/articles/213907285 Plesk's support article].

=== 503 Service Temporarily Unavailable error creating accounts ===

By default, Plesk performs a forced restart of Apache when an account is created or suspended. This causes WHMCS to lose connection to the server, and, if WHMCS is on the same server, you will also lose connection to WHMCS.

To resolve this, see [https://support.plesk.com/hc/en-us/articles/115003664213-Unable-to-create-domain-through-WHMCS-503-Service-Temporarily-Unavailable Plesk's support article].

===Unable to create account in Panel. The field 'username' is required.===

This means the username under the client's '''Products/Services''' tab is empty.

Enter a username, save changes, and try module creation again. Then, ensure that '''Require Domains''' is enabled for the product 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'''.

===0 - Unable to find appropriate manager for this version of Panel. Plesk should be at least 8.0 version===

This is a generic error message that the Plesk module returns. For example, it could indicate a connection error or invalid credentials.

To identify the underlying error that is occurring, check the '''Module Log''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' or, prior to WHMCS 8.0, '''Utilities > Logs > Module Log'''. Enable it, reproduce the error, disable it again, and the ''''Response''' column will show the underlying error.

For more information, see [[Troubleshooting_Module_Problems]].

===1006 - Permission denied===

This indicates that your Plesk login doesn't have the necessary permissions to use the API. You need the server administrator to grant your Plesk reseller account the '''Ability to use remote API''' permission.

===1013 - Template does not exist===

This error message is coming directly from the Plesk API and indicates that the client and domain template names are incorrect or missing. You can correct these in the product's '''Module Settings''' tab.

===1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel===

There are two potential causes of this error message:

==== Incorrect product type ====

The product type is set incorrectly in WHMCS (for example, a reseller plan is configured as a shared hosting product in WHMCS).

To resolve this:

# Log in to WHMCS Admin Area.
# Navigate 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'''.
# Set '''Product Type''' to ''Shared Hosting'' or ''Reseller Hosting'' to match the Plesk plan type.
# Click '''Save Changes'''.

==== Missing data from a table inside Plesk ====

If the error persists after following the ''Incorrect product type'' steps above, see [https://support.plesk.com/hc/en-us/articles/213932225-Error-while-accessing-Plesk-from-WHMCS-via-API-Customer-with-external-id-whmcs-plesk-XX-is-not-found-in-panel this article].

===1013 - Error message: Customer with external id 'xxxxxxxx' is not found in panel===

Refer to the solution for [[#1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel|1013 - Error message: Customer with email 'johndoe@example.com' is not found in panel]] above.

===1014 - Parser error: Request is invalid===

This error message indicates there is a field value missing. This is most commonly caused by having no assigned IP addresses in the client or domain template's IP pool.

===1014 - Parser error: Cannot parse the XML from the source specified===

The Plesk API only supports the characters a-z and 0-9. If the client's profile contains accents or other characters, it will cause account creation to fail. Edit the client's profile to remove these characters.

===1018 - Unable to create hosting. IP address does not exist in client's pool===

This error indicates that there is an issue with the IP address pool configuration in Plesk. For example, there may not be any available IP addresses or the first IP address may be set as dedicated instead of shared.

===1023 - Unable to accept the template: the following limitations are exceeded===

This issue occurs when the resources provided by the serivce plan addon were already used by the subscription.

To resolve this:

# In the subscription for that domain name, remove the referenced addon in Plesk.
# In WHMCS, go to the product or service's '''Products/Services''' tab.
# Use the "Upgrade/Downgrade" option to create an upgrade order.

===2306 - Domain adding was failed. Error: xxxxx template failed: Unable to apply limits===

This error message comes direct from the Plesk API. It indicates that the template you are attempting to use exceeds your limits or has a feature your server doesn't support. Create an account with the template inside Plesk to retrieve further details.

===Plesk login requires user authentication===

This issue can happen when the user has a dynamic IP addresses or an unstable internet connection. Selecting '''Allow IP changes during one session''' in Plesk [https://docs.plesk.com/en-US/obsidian/administrator-guide/server-administration/session-preferences.60305/ will resolve this].

{{modules}}

Domains Management

2022-10-04T11:55:28Z

Lawrence: /* Manually Registering or Renewing a Domain */

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, scroll to the bottom of the page and click the red '''Delete''' link. 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.

Disk Space and Bandwidth Overage Billing

2022-09-13T12:17:11Z

Lawrence: /* Invoicing */

*Overage billing allows you to bill based on the disk and/or bandwidth used for a given month over and above the base amount allowed with a package
*Products can still have a base price or the price and soft limits can be set at zero to bill solely based on the usage
*Usage charges are calculated on the last day of each month
*They can be invoiced on the last day of the month independantly from the related product or added as billable items to be included on the next invoice the client gets sent
*Native support is included for cPanel, Plesk, and DirectAdmin modules using the values returned from the respective control panel API's but this feature can also be used by developers with their own control panels passing usage data direct to the WHMCS database

==How to Configure==

To enable and configure overage billing for a product:

# Go to the '''Other''' 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'''.
# Check '''Overages Billing'''.
# Enter the '''Soft Disk Limit''' and '''Soft Bandwidth Limit''' to include with the package.
# Enter the cost for disk space and bandwidth in your default currency for '''Disk Overages Cost''' and '''Bandwidth Overages Cost'''.
#* You can use up to four decimal places.
#* The system will multiply this by the overused amount.
# Choose the unit of measure for overages (Megabytes, Gigabytes or Terabytes)<br/>1 GB = 1024 MB, 1 TB = 1024 GB.
# Click '''Save'''.
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''.
# Use the '''Overage Billing Charges''' option to choose when clients are invoiced for their overage usage.

==Invoicing==
Overages are calculated with a precision of one tenth of one gigabytyte. For example, an overage of 1.5 GB at $1.00 per GB will bill $1.50.

If you have selected for WHMCS to add the overage charge to the next invoice, it will be added as the final line item on the invoice. Or if the invoice independently option was selected, it will be the sole item on the invoice.

Overage invoice line items are generated with a format as follows:

Shared Hosting - whmcsdemo.com (01/05/2014 - 31/05/2014)
Total Disk Usage = 1.5 GB - Overage Charge = 0.5 GB @ 1.50/GB

Shared Hosting - whmcsdemo.com (01/05/2014 - 31/05/2014)
Total Bandwidth Usage = 7.5 GB - Overage Charge = 2.5 GB @ 2.50/GB

==Custom Fields and Configurable Options==
The overage billing limits for a product can be overridden by custom fields or configurable options named either '''Disk Space''' or '''Bandwidth'''. The values provided will instead be used when performing overage calculations.

For example, if the soft disk limit was set to 10MB, and a configurable option was set to 20MB, then the client would only be charged for overage once they go above 20MB.

When setting up a configurable option for the purpose of overriding overage billing limits, the option type can be any that returns a numerical value (''Drop Down'', ''Radio'', or ''Quantity''). While only numerical values can be used as options, [[Addons_and_Configurable_Options#Friendly_Display_Names|friendly names]] can display non-numerical values to the customer. The unit of measurement is obtained from the '''Other''' tab of the product configuration 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'''. For example:

150|150GB
or
999|999MB

The '''Configurable Option''' value will always use the same unit of measurement configured in the product configuration '''Other''' tab, although [[Addons_and_Configurable_Options#Friendly_Display_Names|friendly names]] allow you to display a different unit of measurement if required. For example, if the product is configured with MB as the unit of measurement but it is desirable to display 10 Gigabytes to clients:

10000|10 Gigabytes

When setting up a '''Product Custom Field''' for the purpose of overriding '''Overage Billing Limits''', the Field Type can be any which returns a numerical value; this would be the Text Box, Drop Down, and Text Area types. Additionally, it is important to note that values defined by a '''Configurable Option''' will override values set by a '''Product Custom Field'''. As with '''Configurable Options''', the unit of measurement is obtained from the '''Other''' tab of the product configuration 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'''.

==Notes==
If you only wish to charge for one of the items (ie. charge only for bandwidth overages) set the soft disk limit to a very high value, say 999999999. That way the user will never exceed it and thus never be charged for any disk overage.

If you'd like to have WHMCS automatically suspend a service when its overage costs are not paid, the ''Include on the Next Invoice'' option must be selected at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, ''Setup > Automation Settings''.

Overage billing may only be configured in your system's default currency. WHMCS will automatically convert overage prices into a client's currency using the rates listed at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Currencies]]''' or, prior to WHMCS 8.0, '''Setup > Currencies'''.

Disk Space and Bandwidth Overage Billing

2022-09-13T12:17:00Z

Lawrence: /* Invoicing */

Domains Management

2022-09-13T11:56:30Z

Lawrence: /* Manually Renewing a Domain */

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, scroll to the bottom of the page and click the red '''Delete''' link. 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 the '''View Invoices''' link 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.

Domains Management

2022-09-13T11:56:19Z

Lawrence: /* Manually Registering a Domain */

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, scroll to the bottom of the page and click the red '''Delete''' link. 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 on 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 the '''View Invoices''' link 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.