Knowledgebase

This script adds a clean, admin-facing form that creates a WHMCS client via API, optionally:

• activates them as an affiliate,

• sends the welcome email,

• opens a support ticket with the client’s website URL + notes,

• logs consent to admin notes and/or ticket,

• uses Country/State/Language dropdowns sourced from your WHMCS install,

• enforces password policy with live hints + confirmation,

• lets admins customize a success message (and optional redirect).

All admin behaviors are controlled in config.php (not exposed on the form).

Requirements

• WHMCS: v8.x (works with v7.10+ in most cases).

• PHP: 7.4 – 8.x with curl and openssl extensions.

• Web server: HTTPS recommended (TLS verification on).

• WHMCS API access with the following Allowed API Actions:

  • AddClient

  • UpdateClient

  • AffiliateActivate (if affiliate activation enabled)

  • OpenTicket (if ticket creation enabled)

Tip: Use a dedicated “API User” with a limited API Role that includes only the actions above.

File Structure

Ship your ZIP with a simple, predictable layout:

• whmcs-add-client.php: The form + handler file (drop-in).

• config.php: All settings: API creds, toggles, messaging, paths, etc.

• Documentation: This guide in HTML/MD.

• Changelog: Versioned changes for marketplaces.

• License: Your license text.

Marketplace best practice: publish config.sample.php in /upload/, and tell users to copy it to config.php so they don’t accidentally overwrite configs during updates.

Step-by-Step Installation

1) Upload files

1. Unzip your package locally.

2. Upload everything inside /upload/ to a secure directory on your server (e.g. /var/www/thexyz/account/add-client/ or /public_html/whmcs-tools/add-client/).

3. Ensure whmcs-add-client.php and config.php are in the same directory.

If you put config.php elsewhere, update the require_once path in whmcs-add-client.php.

2) Prepare WHMCS API credentials

In WHMCS Admin:

• System Settings → Staff Management → API Credentials (older versions: Setup → Staff Management → API Credentials).

• Create a new API Credential (identifier/secret) for a service account user.

• Assign an API Role that includes the required actions (see Requirements).

• If your configuration.php uses an API Access Key, copy that value into config.php $api_access_key.

3) Configure config.php

• Open config.php and set:

API

Admin controls (no UI)

Ticket

Consent + Links

WHMCS filesystem paths for dropdowns

Password policy

Success message + optional redirect

Website URL behavior

4) Find your Support Department ID

• WHMCS Admin → Support → Support Departments.

• Open a department; the ID is visible in the URL (e.g., id=1).

• Put that ID into $TICKET_DEPT_ID.

5) Open the form

Navigate to the URL where you uploaded whmcs-add-client.php (e.g. https://yourdomain.com/whmcs-tools/add-client/whmcs-add-client.php).

Security Best Practices

• Do not hard-code API credentials. Use environment variables or a protected config.php.

• Place config.php outside web root if possible, or deny public access with .htaccess:

   

  # .htaccess next to config.php <Files "config.php"> Require all denied </Files>

• Keep $api_verify_peer = true (default) to validate TLS.

• Serve the page via HTTPS only.

• Consider adding a CSRF token if the page is publicly reachable (simple session token).

• Restrict access (e.g., protect the directory with HTTP auth or IP allowlist) if this is internal-only tooling.

Testing Checklist

1. API connectivity

   • Intentionally break the identifier/secret to ensure you see a helpful error.

2. Client creation

   • Submit the form with test data. Confirm the new client appears in WHMCS.

3. Welcome email

   • Toggle $SEND_WELCOME_EMAIL and watch whether an email is sent (check Email Log).

4. Status & Group

   • Set $CLIENT_STATUS to Inactive or Closed; verify client status afterwards.

   • Set $CLIENT_GROUP_ID to a real group ID; verify assignment.

5. Affiliate

   • Enable $ACTIVATE_AS_AFFILIATE = true; confirm the affiliate profile is created.

6. Ticket

   • Enable $CREATE_TICKET = true; verify a ticket opens in the correct department with website URL + notes.

7. Consent logging

   • Enable $OPTIN_ENABLE and check that consent is written to admin notes and/or ticket when checked.

8. Country/State/Language dropdowns

   • Change country to US/CA and confirm a state select appears; pick a language from /lang.

9. Password policy

   • Verify real-time hints and server-side enforcement; confirm mismatch detection.

10. Success message & redirect

    • Customize $SUCCESS_MESSAGE_TEMPLATE; optionally enable $SUCCESS_REDIRECT_URL and test.

Troubleshooting

Blank Country/Language dropdowns

• Double-check $WHMCS_ROOT path.

• Ensure the following files/directories exist and are readable by PHP:

  • {$WHMCS_ROOT}/resources/country/dist.countries.json

  • {$WHMCS_ROOT}/lang/

“AddClient failed”

• Confirm API Role has AddClient permission.

• Check Response: your script echoes a human-readable message; enable display_errors in dev.

Ticket not created

• Set $CREATE_TICKET = true and a valid $TICKET_DEPT_ID.

• API Role must include OpenTicket.

Affiliate not activated

• Ensure AffiliateActivate permission is granted.

TLS/SSL error

• Make sure the site has a valid certificate; keep $api_verify_peer = true.

Permissions error

• In WHMCS Admin → API Roles, confirm your API user’s role includes all required actions.

Marketplace Packaging (WHMCS Marketplace, Codester, CodeCanyon)

What to include in the ZIP

• /upload/ folder with whmcs-add-client.php + config.sample.php (not config.php to avoid accidental credential leaks).

• /documentation/index.html (this guide, nicely styled).

• /changelog/CHANGELOG.md (semantic versioning recommended: 1.0.0, 1.1.0, etc.).

• /license/LICENSE.txt.

• Optional /screenshots/ for your product page.

Product Page Essentials

• Title: “Add Client to WHMCS (Affiliate + Ticket + Consent)”

• Short description: 1–2 sentences of value.

• Feature bullets:

  • Create clients via API with password policy + double confirm

  • Optional welcome email, affiliate activation, support ticket

  • Admin-only toggles in config.php (no UI exposure)

  • Country/State/Language dropdowns from your WHMCS

  • Custom success message + optional redirect

  • Consent logging (TCPA/CASL/GDPR-friendly)

• Requirements: WHMCS 8.x, PHP 7.4–8.2, cURL.

• Changelog: Paste from CHANGELOG.md.

• Support policy: Response times, supported PHP/WHMCS versions, how to contact.

• Demo (optional but recommended): host a sanitized demo page; stub out API calls or use a staging WHMCS.

Envato (CodeCanyon) Notes

• Provide good documentation (HTML) and clear versioning.

• No encoded/obfuscated code for simple tools; if you encrypt, declare it and provide requirements (e.g., ionCube).

Codester Notes

• Add multiple screenshots; keep description technical but concise.

• Include an install video/GIF if possible.

WHMCS Marketplace Notes

• Ensure compliant with the WHMCS EULA and branding guidelines.

• Provide compatibility info by WHMCS major versions.

• Consider packaging as an “Integration” rather than an addon module (this is a standalone script).

Updating / Upgrading

• Never overwrite a live config.php. Use config.sample.php as the template and diff changes.

• Maintain a CHANGELOG.md with dates and highlights.

• Bump semantic versions (e.g., 1.1.0) when changing config options or adding features.

Optional Hardening (for public-facing installs)

• CSRF protection: add a session token to the form and validate on POST.

• reCAPTCHA: protect from spam if the page is not behind auth.

• Auth guard: wrap the page with simple HTTP auth or an IP allowlist.

Uninstall

• Delete the uploaded directory and any .htaccess protecting config.php.

• API user/role can remain for other integrations or be removed from WHMCS.