Free Trial Manager for WHMCS

Documented release: 1.2.0
Licence product slug: free-trial-manager
Installation directory: modules/addons/amftm

1. Overview

Free Trial Manager creates controlled, automatically provisioned trials for selected recurring WHMCS products. It does not alter the public price configured for the product and does not replace WHMCS billing.

When an eligible customer starts a trial, the module:

Validates the AngleModules licence.
Validates the submitted domain.
Confirms that the customer is eligible.
Selects the first enabled recurring billing cycle with valid pricing in the customer’s currency.
Creates a zero-cost WHMCS order without an initial invoice.
Restores the normal recurring amount and assigns the trial expiry as the next due and invoice date.
Accepts the order and requests automatic provisioning through the product’s existing provisioning module.
Records the trial for expiry processing and repeat-trial prevention.

2. Compatibility and requirements

WHMCS 9.x
PHP 8.2 or 8.3
MySQL 5.7+ or MariaDB 10.3+
PHP cURL and OpenSSL extensions
HTTPS-enabled WHMCS installation
Correct WHMCS System URL
Working WHMCS daily cron
At least one recurring WHMCS product with valid pricing
A working provisioning module attached to every eligible product
A configured WHMCS payment method
Active AngleModules licence

PHP 7.4, PHP 8.4 and older WHMCS releases are not claimed as supported by this release.

3. Before installation

Back up the WHMCS database and files.
Confirm that the target product provisions correctly through a normal paid test order.
Confirm that the product has recurring pricing in every customer currency you intend to support.
Confirm that the WHMCS daily cron completes without errors.
Test on staging before enabling a public trial link.

4. Installation

Extract the release archive locally.
Upload the amftm directory to:
```
/path/to/whmcs/modules/addons/amftm/
```
In WHMCS Admin, open System Settings → Addon Modules.
Find Angle Modules Free Trial Manager and select Activate.
Grant access to the required administrator roles.
Open Addons → Angle Modules Free Trial Manager.
Activate the licence before enabling customer trials.

The module creates its own mod_amftm_* database tables during activation.

5. Licence activation

Open the module’s License tab.
Enter the customer licence key.
Select Activate License.
Confirm that the status is Active and the licensed domain matches the hostname in the WHMCS System URL.

Customers do not enter a public key, private key, API endpoint, or product slug. Those values are embedded in the release.

Licence activation troubleshooting

Message or condition	Likely cause	Corrective action
Licence rejected: inactive	Licence status is not active on AngleModules	Activate or unsuspend the licence in the AngleModules administration panel
Product mismatch	Licence belongs to another product	Issue the licence for `free-trial-manager`
Domain mismatch	WHMCS System URL does not match the licensed hostname	Correct the System URL or reset the authorised activation
Signature verification failed	Wrong/corrupt public key or modified cached response	Restore the original release files and refresh the licence
Remote validation unavailable	Firewall, DNS, TLS or licensing-server problem	Test outbound HTTPS and inspect the signed offline-grace status

Never distribute the AngleModules private signing key.

6. Initial configuration

Trial Rules

Configure:

Enable free trials: master switch for new activations.
Enable landing pages: makes product trial pages and widgets available.
Trial duration: 1–365 days.
Expiry action: suspend, terminate, or use normal WHMCS billing automation.
Repeat-trial prevention: one trial per customer per product, or one trial per customer across all selected products.

Recommended starting configuration:

Setting	Recommended value
Duration	3–7 days
Expiry action	Suspend service
Repeat prevention	Global for high-abuse services; per product for a broader catalogue
Landing pages	Enabled after staging verification

Termination is destructive. Start with suspension until you have tested renewals, reminders and recovery.

Eligible Products

Open Products.
Select only products that have a tested provisioning module and recurring pricing.
Save the configuration.
Copy the generated trial URL from Links & Widgets.

Do not select one-time products. The module requires an enabled recurring billing cycle.

Landing Page

The following values are configurable:

Headline
Supporting message
Badge text
Button text
Feature list, one item per line
Logo URL
Accent colour
Footer note
Optional custom CSS

Use an HTTPS logo URL. Test custom CSS after WHMCS theme updates.

7. Customer flow

Customer opens the product-specific trial URL.
The public page displays the trial offer.
Customer signs in or registers with WHMCS.
Customer enters a valid domain.
The module validates eligibility and creates the service.
The customer is redirected to the WHMCS service page.

The module normalizes the domain, removes a URL scheme/path, requires a full domain extension and validates individual labels. A domain is not registered or transferred by this process.

8. Billing and renewals

No invoice is created for the initial trial order. After order creation, the module restores the regular recurring amount and sets the next invoice and due dates to the trial expiry date.

WHMCS—not this module—creates renewal invoices and sends invoice reminders. Verify:

System Settings → Automation Settings
Invoice generation timing
Overdue reminders
Suspension timing
Payment gateway configuration
Daily cron completion

The invoice expiry option does not itself create or send an invoice. It marks the trial expired and leaves billing activity to normal WHMCS automation.

9. Expiry processing and conversions

The module runs during DailyCronJob.

A paid hosting invoice created after the trial began marks the trial as converted.
An expired unpaid trial is suspended or terminated according to its stored expiry action.
A cancelled, terminated or fraud service is marked expired without another module action.
Provisioning and expiry failures are recorded for administrator review.

Daily cron means expiry processing is not guaranteed at the exact second shown. It occurs when the next successful WHMCS daily cron executes.

Administrators can use Process Expired Trials for a manual check.

10. Dashboard and history

The dashboard reports:

Total trials
Active trials
Converted trials
Expired trials
Conversion percentage
Provisioning/processing errors
Trials expiring within three days

Trial History includes customer, product, service, domain, dates, status, expiry action and any recorded error.

11. Upgrade

Back up WHMCS files and database.
Deactivate customer-facing trial promotion temporarily.
Upload the new amftm directory over the existing module directory.
Do not delete the existing database tables.
Open the addon so WHMCS can invoke its upgrade handler.
Confirm the displayed version and licence status.
Test one internal trial before restoring public links.

12. Deactivation and removal

Deactivation intentionally retains trial history and signed licence information. This prevents customers from receiving another trial merely because the addon was deactivated and reactivated.

Do not manually delete mod_amftm_* tables unless you deliberately intend to erase trial history and have a verified backup.

13. Security guidance

Keep WHMCS and PHP patched.
Use HTTPS for WHMCS and the licensing endpoint.
Restrict addon access by administrator role.
Do not expose licence keys in screenshots.
Retain CSRF protection; do not remove WHMCS token checks.
Review accounts, IP addresses and payment-risk signals outside the module if stronger abuse prevention is required.

Repeat-trial prevention is based on the WHMCS client and stored trial history. It is not device fingerprinting, identity verification or payment-method verification.

14. Common problems

“No product pricing exists for the client currency”

Add recurring pricing for that WHMCS product in the customer’s currency.

“This product has no enabled recurring billing cycle”

Enable at least one recurring cycle. WHMCS represents disabled cycles with negative values.

Order created but provisioning failed

Review the WHMCS order, module log and product provisioning configuration. Test a normal paid order for the same product.

Trial did not expire

Check the WHMCS cron history, module activity log, service status, trial status and configured expiry action.

Customer received no renewal invoice

Check the service’s next invoice date, WHMCS automation settings, cron completion and invoice-generation timing. The module does not independently email an invoice.

Customer can start another trial

Confirm that the customer is using the same WHMCS account, that trial history still exists, and that the intended repeat-prevention scope is selected.

15. Known limitations

Trial configuration uses one global duration and expiry policy for new trials.
The module selects the first enabled recurring billing cycle; the customer does not choose a cycle on the trial page.
It does not register or transfer domains.
It relies on the selected product’s provisioning module.
It relies on WHMCS for invoices, reminders, payments and standard billing automation.
It does not provide advanced identity, device or payment-method fingerprinting.
Expiry processing follows the WHMCS daily cron schedule.

16. Support checklist

Include the following with a ticket:

Module version
WHMCS/PHP versions
Product ID and service ID
Customer currency and enabled billing cycles
Trial status and expiry time
Exact error text
Redacted module/activity logs
Result of a normal paid provisioning test