The Problem
WHMCS coupon codes are public. Anyone who finds a code can use it. This creates issues for businesses running VIP programs, partner contracts, or exclusive discounts.
What WHMCS Does
Standard WHMCS promotion codes work like this: 1. Admin creates coupon code 2. Code works for anyone who has it 3. No client restrictions 4. No automatic application
Result: Coupon codes leak. VIP codes end up on coupon sites. Partners share codes with non-partners. Corporate contracts can't enforce per-client pricing.
The Gap
Common scenarios WHMCS can't handle:
VIP client programs - You want client #247 to get 20% off automatically. WHMCS requires manual coupon entry every time. Code leaks to other clients.
Partner/reseller pricing - Partners get special rates. You give them code PARTNER20. They share it publicly. Everyone uses it.
Corporate contracts - Company X negotiated 15% off. You create COMPANYX15. Their employees share it externally. Unauthorized users get corporate pricing.
Loyalty discounts - Long-term clients deserve automatic discounts. WHMCS can't restrict codes to specific clients or auto-apply them.
Workarounds Don't Work
Hidden product method: Create free "VIP" product, require it for promotion, manually add to clients. Clunky. Clients see fake product in their services. Still requires manual coupon entry.
Manual admin application: Apply coupons to services after purchase. Time-consuming. Doesn't work for new orders. Clients see full price at checkout.
Honor system: Tell VIP clients "use code VIP20." They forget. Code leaks anyway. No enforcement.
Custom pricing per client: Edit product pricing in client profile. Doesn't scale. Maintenance nightmare. Can't use WHMCS promotions features.
None of these solve the core problems: automatic application and access restrictions.
The Solution
Coupon Client associates specific clients with specific coupon codes. When authorized clients view their cart, the coupon applies automatically. Unauthorized clients can't use restricted coupons at all.
How It Works
Association system: - Link client #247 to coupon VIP20 - Activate association - Client #247 sees VIP20 applied automatically at checkout - Other clients can't use VIP20 even if they know the code
Restriction enforcement: - Coupons with active associations become restricted - Only assigned clients can use them - Unauthorized attempts blocked with error message - Coupon removed from cart immediately
Multiple clients, one coupon: - Assign VIP20 to clients #247, #891, #1052 - All three get automatic discount - Everyone else blocked
Flexible management: - One active coupon per client (prevents stacking abuse) - Create multiple associations, activate one at a time - Switch between different discount programs - Deactivate all associations to make coupon public again
Real-World Usage
VIP Program:
Client John Doe → Coupon VIP20 (active) → Automatic 20% off
Client Jane Smith → Coupon VIP20 (active) → Automatic 20% off
Client Random User → Tries VIP20 → Blocked: "Not valid for your account"
Partner Pricing:
Partner Company A → Coupon PARTNER15 (active) → Auto-applied
Partner Company B → Coupon PARTNER15 (active) → Auto-applied
Non-partner tries PARTNER15 → Blocked
Corporate Contract:
ACME Corp employees → Coupon ACME10 (active) → Auto-applied
Code ACME10 shared on Twitter → Other users blocked
Technical Implementation
Auto-Apply: - Logged-in client views cart - Module checks for active association - Validates coupon (expiration, limits, restrictions) - Applies automatically (no manual entry) - Maintains throughout checkout
Restriction Enforcement: - Cart validation on page load - Checks if coupon has active associations - Verifies client is authorized - Removes unauthorized coupons with error - Works for manual entry and URL parameters
Priority Modes: - Client First (default): Auto-assigned coupon overrides manual entry - Manual First: Manual entry allowed, auto-apply only if cart empty
Notification Options: - Silent (default): Apply without message (clean UX) - Notification: Show "Discount applied" message
Installation
- Purchase from here
- Upload to
/modules/addons/coupon_client/ - Activate in Setup → Addon Modules
- Enter license key
- Done
Module creates database table and loads hooks automatically.
Usage
Creating Associations
Admin Area → Addons → Coupon Client
- Search for client (name, email, company)
- Select coupon from dropdown
- Add optional notes
- Click "Add Association"
Rules: - One active coupon per client - Multiple inactive associations allowed (for future use) - Multiple clients can share same restricted coupon - Activating second coupon requires deactivating first
Coupon States: - No associations: Public (normal WHMCS behavior) - Has active associations: Restricted to assigned clients only - All associations deleted/inactive: Returns to public
Managing Associations
Search and Filter: - Search by client name, email, or coupon code - Filter by status (all/active/inactive) - 25 results per page
Actions: - Activate/Deactivate - Delete - View in client profile
Validation Warnings: - Expired coupons highlighted - Usage limit reached shown - Duplicate prevention
Client Experience
Authorized Client: 1. Logs into WHMCS 2. Adds product to cart 3. Views cart 4. Discount applied automatically 5. Sees discounted total 6. Completes checkout
Unauthorized Client: 1. Somehow obtains restricted code 2. Enters code manually 3. Error: "This coupon code is not valid for your account" 4. Coupon removed from cart 5. Normal pricing shown
Client Area Widget: Active discount shown in sidebar:
Your Active Discount
VIP20: 20% Off
Configuration
Auto-Apply Mode: - Silent: No notification (default - cleaner) - Notification: Shows "Discount applied" message
Priority Mode: - Client First: Auto-assigned overrides manual (default - prevents confusion) - Manual First: Manual entry works, auto-apply as fallback
Settings apply globally. No per-client configuration needed.
Technical Details
Database: Table: mod_coupon_client - Client ID and Promotion ID linkage - Active/inactive status - Creation tracking - Optional notes - Indexed for performance
Hooks: - ClientAreaPageCart - Validates restrictions, auto-applies coupon - PreCalculateCartTotals - Maintains coupon during calculations - ClientAreaHeaderOutput - Shows notifications - ClientAreaPrimarySidebar - Displays widget - AdminClientProfileTabFields - Admin profile integration - ShoppingCartValidateCheckout - Final validation before order
Security: - SQL injection protection (Capsule ORM) - XSS protection (htmlspecialchars) - Input validation - License verification
Performance: - AJAX search for large databases - Pagination - Database indexes - Only active associations queried
Troubleshooting
Coupon not applying: - Check association is Active (not just created) - Verify client is logged in - Check coupon not expired - Verify usage limits not reached - If Manual First mode: check client hasn't entered different coupon - Only one coupon can be active per client
Coupon being rejected: "This coupon code is not valid for your account"
Coupon has active associations and is restricted. Fix: - Add client to authorized list - Or delete/deactivate all associations to make public
Multiple active coupons error: "This client already has an active coupon assigned"
Only one active per client. Deactivate existing before activating new.
License errors: - Verify license key correct - Check domain authorized with ArkHost - Verify firewall allows HTTPS to arkhost.com - Contact support with server details
Use Cases
VIP Client Program: - Identify top 10% revenue clients - Create VIP20 coupon - Associate all VIP clients - They get automatic 20% off forever - No manual codes, no leaks
Partner/Reseller Pricing: - Partner companies get special rates - Create PARTNER15 coupon - Associate partner client accounts - Partners can't share code (restricted) - Easy to add/remove partners
Corporate Contracts: - Company negotiates bulk pricing - Create COMPANY10 coupon - Associate all company employee accounts - Employees get automatic discount - Code can't be used by outsiders
Loyalty Programs: - Clients after 1 year get 5% off - Clients after 3 years get 10% off - Create LOYAL5 and LOYAL10 coupons - Switch associations as clients reach milestones - Automatic application, no client action needed
Beta Tester Incentives: - Beta testers get 50% off specific products - Create BETA50 coupon - Associate beta tester accounts - Coupon only works for authorized testers - Easy to add testers, remove after beta
Employee/Internal Pricing: - Staff get company services at cost - Create STAFF0 coupon (100% or fixed discount) - Associate employee accounts - Prevents friends/family using staff codes
Comparison: Standard WHMCS vs Coupon Client
Standard WHMCS:
Create coupon VIP20
→ Anyone with code can use it
→ Client must remember to enter code
→ Code leaks to coupon sites
→ VIP pricing available to everyone
→ Manual enforcement impossible
With Coupon Client:
Create coupon VIP20
→ Associate with specific clients
→ Auto-applies for authorized clients
→ Blocked for unauthorized clients
→ VIP pricing enforced
→ No leaks possible
When You Need This
Required if: - Running VIP/loyalty programs - Have partner/reseller pricing - Corporate contracts with specific clients - Want to prevent coupon leaks - Need automatic discount application - Per-client pricing enforcement
Not required if: - All coupons are public - Don't care about code leaks - No client-specific pricing - Manual coupon entry acceptable
Language Support
- English
- German (Deutsch)
- French (Français)
- Spanish (Español)
- Dutch (Nederlands)
- Russian (Русский)
Add more by copying modules/addons/coupon_client/lang/english.php and translating.
Why This Exists
ArkHost runs VIP programs and partner contracts. WHMCS coupon codes kept leaking. Partners shared codes publicly. VIP clients forgot to enter codes.
Standard WHMCS workarounds (hidden products, manual application) were clunky and didn't scale.
Built this module to solve it properly: automatic application + access restrictions.
In production at ArkHost. Works reliably. Made available to other businesses with same problem.
Technical Specifications
Requirements: - WHMCS 8.9+ - PHP 7.4+ - MySQL 5.7+
File Structure:
modules/addons/coupon_client/
├── coupon_client.php Main module + hooks
├── hooks.php Hook handlers
├── license.php License verification
└── lang/ Translations
All files in module directory. No external dependencies.
Support
Before contacting support: 1. Check WHMCS Activity Log for "Coupon Client" entries 2. Verify license valid 3. Test with simple scenario (one client, one coupon) 4. Check Troubleshooting section
When reporting issues: - WHMCS version - PHP version - Module version - Steps to reproduce - Activity Log errors
