Licensing and Pro activation
The Free plan is a supported, permanent way to run Perfex CRM Integration for WHMCS. It syncs clients and contacts one way, from WHMCS into Perfex, in real time. You never need a key for that.
A Pro licence unlocks the rest. This page covers buying it, activating it, checking it, and removing it.
What Pro unlocksโ
| Unlocked by Pro | What it means day to day |
|---|---|
| ๐ Two-way client and contact sync | An address corrected in Perfex flows back into WHMCS, under the conflict policy you chose |
| ๐ Invoice mirroring | WHMCS invoices appear on the Perfex customer with their line items, tax row and status |
| ๐ณ Payment and transaction sync | A paid WHMCS invoice flips its Perfex mirror to Paid, with the gateway and transaction ID recorded |
| ๐ Order sync | A WHMCS order becomes a Perfex lead, or a note on the customer, or nothing, as you prefer |
| ๐ซ Support ticket sync | Tickets, replies and status changes flow in both directions, with optional per-ticket Perfex tasks for timesheets |
| ๐ Services and domains panel | A WHMCS tab on every Perfex customer profile, listing that client's services and domains |
| โฌ Backfill wizard | Import your existing clients, invoices, services and domains, not just new activity |
| ๐๏ธ Department mapping dropdowns | Map WHMCS ticket departments to Perfex departments by picking from a list instead of typing IDs |
The full side-by-side comparison is in the Free vs Pro table.
The Perfex companion is free and never holds a key. The WHMCS addon decides the plan and tells Perfex what it is, so the Perfex settings page can explain why two-way sync is or is not running. Your licence key itself never travels to Perfex.
Buying Pro: the checkout overlayโ
This is the fast path, and it needs no copy-paste at all.
- On either admin page, click an upgrade link:
- WHMCS: Addons > Perfex CRM Bridge. The link appears as Buy a Pro licence next to the Pro License Key box, and as Upgrade to Pro on the licence checklist row and in the Pro teaser boxes.
- Perfex: Setup > WHMCS Bridge, the WHMCS plan panel, button Upgrade to Pro.
- A secure checkout overlay opens in place, on top of the page you were already on.
- Complete the purchase.
- Activation happens automatically:
- Started from WHMCS: the licence key from the checkout response is written into the settings form's own Pro License Key box and that form is submitted for you. The save verifies the key live, flips the plan to Pro, and tells the Perfex side, all in the same request.
- Started from Perfex: the key is relayed to your WHMCS installation over the signed bridge channel. WHMCS verifies it live before storing anything, activates Pro, and pushes the fresh plan state straight back, so the Perfex plan panel flips to Pro in place without a reload. Perfex never stores the key.
- Pro is live immediately. There is no waiting for a cron tick, and nothing to type.
If the overlay script is blocked by a browser extension, a strict content-security policy or a slow network, the link simply behaves as it always did and opens the hosted checkout page in a new tab. Nothing breaks; you just finish with the manual paste below.
If the browser closed before activation finishedโ
You still have your key. Two safety nets, in order:
- On the page. If the purchase succeeded but automatic activation could not run, the key is shown on the page in a selectable field, with a Copy button on the Perfex side, and exact instructions for where to paste it. A paid key never exists only inside a closed overlay.
- In your inbox. The key is always emailed to you at purchase, and it is also available in your customer portal at the payment provider. If the browser crashed at the wrong moment, check your email.
Then follow the manual path below.
Activating a key manuallyโ
Use this whenever you already have a key: from the purchase email, from your customer portal, or when moving a licence to a different WHMCS installation.
- In WHMCS, open Addons > Perfex CRM Bridge.
- Scroll to Settings > Pro licence.
- Paste the key into Pro License Key. Keys begin with
sk_. - Click Save Settings.
That is the whole activation. Saving a key that has actually changed runs the live check there and then, so the page comes back already showing your plan. You do not need to press anything else, and you do not need to wait for a cron tick.
The banner tells you exactly one of three things:
| Banner | Meaning | What to do |
|---|---|---|
| ๐ข Green - "Settings saved. Licence verified - your Pro plan is active..." | The licence server confirmed the key. The page header and the License / plan checklist row already say Pro, the Pro teaser boxes are gone, and the backfill wizard is unlocked. | Nothing. You are done. |
| ๐ด Red - "Settings saved. The licence server rejected this key..." | The key was refused, and the message names the server's own reason: an unknown key, an expired subscription, a cancelled licence, or the activation quota already used up. | Check the key is pasted exactly as it appears in your purchase email, with no missing or extra characters, then save again. |
| ๐ Amber - "Settings saved. Could not reach the licence server..." | Neither an approval nor a rejection: your server could not reach the licensing service right now. | The key is saved and retries continue automatically. Check that your server can reach api.freemius.com over HTTPS, then click Check licence now. The grace period protects you meanwhile. |
The settings are written to the database before any licence check runs, so a red banner never means "your save failed". It means "saved, and your key was refused". You never have to re-type the form.
Only a licence key that actually changed triggers a check. Pausing sync, changing the order target or editing the ticket reply admin makes no network call at all, and the banner stays a plain "Settings saved."
Check licence nowโ
The Check licence now button sits at the top of the WHMCS module page, next to Test Connection and Run Sync Now.
It forces an immediate re-check of the key already stored, ignoring the once-a-day throttle. Use it when:
- you have just renewed or extended your licence and want Pro back straight away;
- a save came back amber and you have since fixed the network or firewall problem;
- you want to confirm the current state before opening a support ticket.
The button has a short anti-double-click cooldown of a few seconds. Press it twice in a row and the second press answers "checked a moment ago" without sending a second request. Wait a few seconds and it checks again normally.
With no key stored at all, the button answers with a red banner saying the key is empty and the install is on the Free plan. No request leaves your server.
Staying activated: daily re-check and the 14-day grace periodโ
Once a key is stored, the WHMCS cron re-validates it once a day. You do not have to do anything.
If the licensing service cannot be reached, the module does not switch you off. That case reads as "we do not know", never as "rejected", and a 14-day grace period keeps Pro fully working while it retries.
Three details worth knowing:
- The grace clock runs from the last successful check, not from the last attempt. The countdown shown on the page is genuine days remaining, and it does not reset itself every time a retry fails.
- A real rejection ends grace immediately. If the licensing server actively says the licence is expired, cancelled or invalid, that is an answer, and grace does not apply. Blocking the licensing endpoint at your firewall cannot keep a revoked licence alive.
- Grace extends, it never bootstraps. A key that has never once been confirmed has no grace to ride on. If you paste a brand-new key while the licensing service is unreachable, the key is stored and retried, but Pro does not turn on until a check actually succeeds.
Plan states you may see in the page headerโ
| Header text | Meaning |
|---|---|
Free plan - no licence key set. | No key. This is the Free tier, working normally. |
Pro license set - awaiting first verification. | A key is stored but has never been confirmed. Click Check licence now. |
Pro active until YYYY-MM-DD (UTC) | Everything is fine. |
Pro active - lifetime licence | A licence with no expiry date. |
Pro (grace) - could not reach the licence server, retrying daily. Pro keeps working for N more day(s). | Temporary outage. Nothing is broken for you yet. |
Free plan - this licence has expired. | Renew, then click Check licence now. |
Free plan - this licence was cancelled. | The licence was cancelled or refunded. Contact support if that is a mistake. |
Free plan - the licence key was rejected. | Wrong key, or the activation quota is used up. The message carries the server's own wording. |
Free plan - the licence server could not be reached and the grace period has run out. | Fix connectivity to the licensing endpoint, then click Check licence now. |
The same sentence appears in the License / plan row of the setup checklist, so you never have to hunt for it.
Activation slotsโ
One WHMCS installation consumes one activation slot on your licence. The module generates a stable identifier once and reuses it forever, so re-checking, re-saving or moving your site to a different domain never burns a second slot.
If you see a rejection mentioning that the licence is already in use on the maximum number of installations, either remove the key from the installation that no longer needs it, which releases the slot immediately, or contact support about your quota.
Removing a key and reverting to Freeโ
- In WHMCS, open Addons > Perfex CRM Bridge > Settings > Pro licence.
- Tick Remove the stored key (revert to Free).
- Click Save Settings.
What happens:
- The install reverts to Free immediately, whatever is still cached. Pro features stop.
- The activation slot is released, so the licence can be activated on another installation.
- The Perfex side is told about the downgrade, so its WHMCS plan panel does not keep advertising Pro for the rest of the day.
If you delete a WHMCS installation without removing the key first, its activation slot stays consumed. Removing the key takes five seconds and saves a support round trip later.
What happens to your data when Pro endsโ
Nothing is deleted. On a Free install:
- Client and contact sync keeps working, one way, exactly as it always did.
- WHMCS stops queueing invoice, payment, order, service, domain and ticket events. The gate sits at the source, so nothing accumulates and nothing retries pointlessly.
- Perfex-side changes that were already queued for WHMCS are refused with a clear "Two-way sync requires Pro on the WHMCS side" message on the Outbound queue panel, retried, and eventually dead-lettered.
- Everything already synced stays in Perfex. The WHMCS tab on customer profiles still renders the last stored snapshots; it just stops updating.
Re-activate a valid key and everything resumes on the next event.
Licensing troubleshootingโ
| Symptom | Cause | Fix |
|---|---|---|
| Saving a key does nothing visible | You pasted the same key that was already stored. Only a changed key triggers a check. | Click Check licence now. |
| Banner is amber every time | Your server cannot reach the licensing endpoint over HTTPS. | Allow outbound HTTPS to api.freemius.com through any egress firewall or proxy on the WHMCS server. Then click Check licence now. |
| "The licence key was rejected" with a correct-looking key | A truncated paste, or the activation quota is exhausted. | Re-copy the key from the purchase email in one go. Keys are 32 characters and may contain punctuation, so do not trim anything. If the message mentions installs, free a slot. |
| Perfex still shows Free after WHMCS shows Pro | The plan state had not reached Perfex yet. | Click Check licence now or Test Connection in WHMCS; both deliver the plan state to Perfex on the spot. Reload the Perfex settings page. |
| Perfex plan panel says Unknown | The WHMCS side has never reported, or has not reported for a long time. | Click Test Connection in WHMCS, then reload the Perfex page. If it stays Unknown, the WHMCS cron may have stopped, or the two sides are no longer paired. |
More in Troubleshooting.