WHMCS Migration

What WHMCS Migration does

The WHMCS Migration tool imports your existing billing data — clients, products, services, invoices, payments, tickets and more — directly from a WHMCS install into FluxBilling. It connects to your WHMCS MySQL database (optionally through an SSH tunnel) and walks you through a six-step wizard so you can pick exactly what to bring over, decide how conflicts are handled, preview the result, and watch the import run in real time.

How to open it

Go to Settings in the admin panel, open the Migration Tools group in the settings menu, and choose WHMCS Migration. A progress bar across the top shows the six stages: Connection → Data Selection → Conflicts → Preview → Progress → Results, along with a Step N of 6 indicator. (The sibling entry, EasyDCIM Migration, works the same way for a different source.)

Before you start, take a fresh backup of your FluxBilling data. The import writes real records, and while you can re-run it safely with the right conflict settings, it is much easier to restore from a backup than to unpick a bad run.

Step 1 — Connection

This step tells FluxBilling how to reach your WHMCS database. All data is read directly from MySQL, so a working database connection is required before you can continue.

1. Fill in the MySQL Connection fields: MySQL Host, Port (default 3306), Database Name, Username and Password. The username and password fields have an eye icon to reveal what you typed.
2. If the database is not reachable directly from your server, turn on Use SSH Tunnel and enter the SSH Host, Port (default 22), Username and Password to connect through the SSH server first.
3. Click Test. On success a green banner reads Connected! and shows a quick count of clients, products, invoices and services found.
4. Optionally click Save to store the connection details so they load automatically the next time you open this tab.
5. Click Next to continue. If you have not tested yet, clicking Next runs the test for you and only advances if it succeeds.

Optional: migrating saved payment tokens

The amber CC Encryption Hash box lets you decrypt stored payment tokens (such as Stripe and PayPal vault references) so saved payment methods come across intact. Paste the cc_encryption_hash value from your WHMCS configuration.php file. Leave it blank if you do not need to migrate saved cards.

When the SSH tunnel is enabled, a blue WHMCS Installation Path box also appears (default /var/www/whmcs). This is the server path to your WHMCS folder; it is used to decrypt payment tokens directly and works even if the WHMCS license has expired.

If you migrate payment tokens, you must update the webhook URLs in your payment provider dashboards (Stripe, PayPal, etc.) to point at FluxBilling after the import. Until you do, recurring charges will keep notifying WHMCS instead of your new system, and payments can fail. The wizard reminds you of this on the Preview and Results steps.

Step 2 — Data Selection

Choose which data types to bring over. Each row is a card with a checkbox and the number of records found. Some types depend on others; if a dependency is unchecked, the dependent card is greyed out and shows a Requires: note. The defaults are sensible for most migrations.

Product options

When Products is selected, the card expands with extra controls:

• Product & category picker — products are listed grouped by category, with per-category checkboxes and All / None shortcuts so you can import a subset. The header shows how many products are selected out of the total.
• Module mapping — each WHMCS server module is matched to one of your infrastructure plugins. Use Auto-detect to match by name, or leave a module on No plugin (skip) to import the product without one. If you have no infrastructure plugins enabled yet, a note points you to set them up in Visual Plugins first; unmapped modules simply import without a plugin.
• Import configurable options — turn this on to bring across WHMCS configurable options. Each option is auto-categorised (RAM, Storage, Bandwidth, Network, OS, Location or General); you can deselect individual options, override a category, or map an option to a plugin slug (or let FluxBilling auto-generate one).

Service options

• Skip modules — checkboxes for each discovered server module so you can exclude services tied to a particular module.
• Link infrastructure devices — on by default; attaches imported services to matching infrastructure.
• Ignore missing device links — shown only when device linking is on; lets the import continue past services whose device cannot be matched.

Invoice options

• Types — Invoices and/or Proforma.
• Statuses — Paid, Unpaid, Cancelled, Refunded, Collections, Draft and Payment Pending; deselect any you do not want.
• Proforma statuses — control which proforma statuses come across.
• Include invoice items — bring across the individual line items on each invoice.

Gateway mapping

When you select Payments or Payment Methods, a mapping table lists each WHMCS gateway name with a dropdown to match it to one of your FluxBilling payment methods. Any gateway left as Skip (don't migrate) is ignored, and the table tells you how many gateways are still unmapped. If no payment gateways are configured in FluxBilling yet, a warning prompts you to set up payment gateway plugins first.

Step 3 — Conflicts

Decide what happens when an incoming record matches one that already exists in FluxBilling. A dropdown is shown for each selected type that supports conflict handling, with the matching key in brackets.

Two extra checkboxes sit below:

• Create migration log — on by default; records what was imported.
• Dry run (preview only) — runs the whole process without writing any data, so you can validate counts and mappings first. When enabled, the action button later reads Start Dry Run.

The default is Skip for every type. That makes re-running the wizard safe — already-imported records are left untouched — but it also means a second run will not overwrite existing records unless you switch them to Update existing.

Step 4 — Preview

A summary table lists every selected data type with its record count, the conflict rule that will apply, and a Ready status. Below it, badges summarise your key choices — an estimated time, a Passwords from DB note, how many module mappings and category overrides you set, and whether device linking, payment-token decryption or dry run are active. A caution line reminds you to have a backup. Click Back to adjust anything, or Start Migration (or Start Dry Run) to begin.

Step 5 — Progress

Once started, the wizard streams live progress for each entity it processes — Company Details, Admin Users, Clients, Contacts, Product Categories, Products, Configurable Options, Services, Invoices, Tickets, Payments, Credits, Payment Methods and Auto-Renewal Linking — with a per-type progress bar and running created/updated/failed counts. You can click Cancel here (it asks for confirmation first); cancelling returns you to the Preview step.

Step 6 — Results

When the job finishes, a header shows whether the migration Completed, Failed or was Cancelled, along with the finish time. A results table breaks down Created, Updated, Skipped, Failed and Total for each data type, with a grand-total row. If anything failed, an error list appears below it.

• Report — downloads a file with the full job details, configuration and any errors for your records.
• New Migration — resets the wizard back to the Connection step so you can run another import. Your saved connection details are kept.

If you migrated saved payment methods, a reminder confirms you must update your payment-gateway webhook URLs before recurring charges will work.

Tips and gotchas

• Validate first. Use Dry run to confirm record counts and mappings before committing a real import.
• Mind the dependencies. Services need both Clients and Products; Invoices, Tickets and Credits need Clients; Payments need Clients and Invoices; Payment Methods need Clients and Services. Unchecking a parent automatically disables its dependents.
• Set up plugins early. Module and gateway mapping only offer targets that already exist. Configure your infrastructure and payment-gateway plugins before migrating so services and payments link correctly.
• Re-running. With conflict rules on Skip, you can safely run the wizard again to pick up data types you left out the first time.

Related

EasyDCIM Migration, Clients, Products, Payment Gateways.