WHMCS Software Licensing Documentation

WHMCS Software Licensing Addon - Official Documentation

Welcome to the WHMCS Software Licensing Addon! This powerful tool turns your WHMCS installation into a complete digital delivery and licensing platform. With it, you can automatically generate license keys, securely validate them via a remote API, and prevent unauthorized distribution of your PHP applications.

This guide will walk you through installing the addon, configuring your first product, and integrating the license check into your software.

1. Installation

1. Download and Extract: Extract the ZIP file you downloaded after purchasing this addon.
2. Upload Files: Upload the modules folder from the extracted files directly to the root directory of your WHMCS installation (e.g., /public_html/whmcs/). This will place the required files into the modules/addons/ and modules/servers/ directories.
3. Activate the Addon:
   • Log in to your WHMCS Admin Area.
   • Navigate to System Settings (the wrench icon in the top right) > Addon Modules.
   • Locate Software Licensing in the list and click Activate.

2. Configuration & Setup

Once activated, you need to configure the global settings for the module.

1. Still on the Addon Modules page, click Configure next to Software Licensing.
2. Secret Key: Generate a long, random string (e.g., s3cr3t_K3y_98765!) and paste it here. Do not lose this key. You will need it later when integrating the code into your software.
3. Public Verification Tool: Check this if you want a public page where users can check if a domain holds a valid license for your software.
4. Access Control: Select which admin roles (e.g., Full Administrator) should have access to the Licensing Manager.
5. Click Save Changes.

3. Creating a Licensed Product

Now, you will create a product in WHMCS that automatically generates a license key when purchased.

1. Go to System Settings > Products/Services.
2. Click Create a New Product.
   • Product Type: Other
   • Product Group: (Select your desired group)
   • Product Name: (e.g., "My Awesome Script License")
3. Navigate to the Module Settings tab.
4. From the Module Name dropdown, select softwarelicensing.
5. Configure the following fields:
   • Key Prefix: An optional prefix for your keys (e.g., MYAPP-).
   • Key Length: The number of random characters to generate (e.g., 12 will generate a key like MYAPP-aB3dE5fG...).
   • Allow Client Reissue: Tick this to allow clients to reissue their license to a new domain directly from their WHMCS Client Area.
   • Conflict Toggles: Leave these unticked for strict security. Ticking them bypasses the check for matching Domains, IPs, or Directories.
6. Set up your Pricing and other product details as normal, then click Save Changes.

Your WHMCS is now ready! Whenever a client orders this product, WHMCS will automatically generate a license key and display it in their client area.

4. Managing Licenses

You can view and manage all issued licenses from the central dashboard.

1. In the WHMCS Admin Area, go to Addons (in the top menu) > Software Licensing.
2. Here you will see a table of all active, suspended, and reissued licenses.
3. You can see exactly which Domain, IP Address, and Directory the license is bound to.
4. Click Manage Service to jump directly to the client's product page, where you can manually Reissue or Revoke the license using the Module Command buttons.

5. Integrating the License Check into Your Software

To actually protect your software, you need to tell it to "call home" to your WHMCS server to verify the user's license key. Included in your download is a file called check_sample_code.php.

Step 1: Add the Code to Your App

1. Open your software's main configuration or bootstrap file (a file that loads on every single page view).
2. Include the check_license function from the sample code.
3. Update the configuration variables at the top of the function:

$whmcsurl = 'https://www.yourbillingdomain.com/whmcs/'; 
$secret_key = 'THE_SECRET_KEY_YOU_SET_IN_STEP_2'; 

Step 2: Enforce the Check

In your application, you must pull the user's saved License Key and Local Key from your application's database, run the check, and stop execution if the license is invalid.

// Fetch these from your app's database
$savedLicenseKey = get_database_setting('license_key'); 
$savedLocalKey = get_database_setting('local_key');

$results = check_license($savedLicenseKey, $savedLocalKey);

if ($results['status'] === 'Active') {
    // License is valid! 
    // Save the new local key to the DB if it changed to speed up future loads
    if (!empty($results['localkey']) && $results['localkey'] !== $savedLocalKey) {
         update_database_setting('local_key', $results['localkey']);
    }
} elseif ($results['status'] === 'Suspended') {
    die("Your license is suspended due to an unpaid invoice. Please renew.");
} elseif ($results['status'] === 'Expired') {
    die("Your license has expired.");
} else {
    die("Invalid License. Please ensure your license is active and reissued for this domain.");
}