Docs Changelog Marketplace

WHMCS Integration

The WHMCS tile shows live data from your own WHMCS installation on your dashboard: income, unpaid and overdue invoices, services and monthly recurring revenue, orders, clients and support tickets. It can also add your paid WHMCS invoices to your Tilelytix finance.

Before you start

  • A WHMCS installation reachable over https:// from the internet. Tilelytix never connects to a plain http:// address or to a private or local network address (such as 10.x, 192.168.x or localhost).
  • An administrator account in WHMCS that can manage API credentials.
  • The WHMCS tile in your organization (Your Tiles, or included in your plan).

1. Create an API role in WHMCS

  1. In the WHMCS admin area, open System Settings (the wrench icon) and choose API Roles.
  2. Choose Create API Role and name it, for example Tilelytix (read only).
  3. Tick only these actions: GetStats, GetInvoices, GetOrders, GetClients, GetClientsProducts, GetTickets and GetTransactions. They only read data; the tile never changes anything in WHMCS.
  4. Save the role.

2. Create the API credential

  1. Still in System Settings, open API Credentials and choose Generate New API Credential.
  2. Pick an admin user, and assign the role you just created.
  3. Copy the Identifier and the Secret. WHMCS shows the secret only once.
Keep this credential for Tilelytix only. If you ever want to cut Tilelytix off, delete it in WHMCS and nothing else is affected.

3. IP restrictions (only if you use them)

WHMCS can refuse API requests from IP addresses that are not on its allow-list. Tilelytix runs on cloud hosting without fixed addresses, so instead set an API access key: add the line $api_access_key = 'a-long-random-value'; to your WHMCS configuration.php, and enter the same value in the tile's API Access Key field. Leave the field empty if your API is not IP-restricted.

4. Configure the tile

  1. On the dashboard, choose the gear on the WHMCS card (or Configure in Your Tiles).
  2. WHMCS API URL: your installation's API address, for example https://billing.example.com/includes/api.php.
  3. API Identifier and API Secret: from step 2.
  4. API Access Key: only if you set one in step 3.
  5. Save. The tile loads straight away.

Views

The card has a view switcher and remembers your last choice. In edit mode, Add view pins any view as its own card (see Views).

  • Overview: income today, this month, this year and all time (as WHMCS reports it), unpaid and overdue invoice counts, pending orders, tickets awaiting a reply, pending cancellations, and a 30-day income chart.
  • Revenue (90 days): income, expenditure and net over 90 days, with a chart, in your WHMCS default currency.
  • Unpaid invoices: by due date, with the total outstanding.
  • Overdue invoices: invoices past their due date.
  • Recently paid: the latest paid invoices with payment date and method.
  • Services & MRR: active services, estimated monthly recurring revenue (each service's recurring amount divided by its billing cycle in months) and renewals due in the next 30 days.
  • Recent orders: with order and payment status.
  • Clients: your newest clients.
  • Support tickets: active tickets with status and priority.

Add WHMCS income to your finance

Tick Include in Tilelytix finance in the tile's settings (your plan needs the finance feed feature). Then:

  • Every paid invoice counts as income on the date it was paid.
  • Gateway fees recorded on WHMCS transactions count as expenses.
  • A whole-invoice refund (the invoice status becomes Refunded) counts as an expense. A partial refund on an invoice that stays Paid is not seen.
  • Only invoices in your organization's currency are counted; others are listed as not counted. Nothing is converted.
  • Use Count from if sales before a date were already entered by hand; leave it empty to import all history.
Do not also enter these sales as manual income, and do not turn on the Razorpay tile's finance feed if Razorpay collects your WHMCS payments: the same sale would be counted twice.

The newest invoices appear at once; older history is imported in the background while your dashboard is open, and a sync runs every day. The tile's settings show the last sync, the number of records, any problem, and Sync now. Unticking the box removes the records from your totals without deleting them. More in Add integration income to your finance.

Privacy and security

  • Your identifier, secret and access key are encrypted when saved and are never shown again.
  • Requests to WHMCS are made by Tilelytix's server, which refuses redirects and private addresses, stops after 10 seconds and reads at most 2 MB per answer. The tile's own code never sees your credentials.
  • Money for the finance feed is read by Tilelytix's own WHMCS adapter, never by the tile's script.

Troubleshooting

  • "Add your WHMCS credentials": a required setting is empty. Open the settings and fill in the URL, identifier and secret.
  • "Invalid IP" or "Authentication Failed": WHMCS refused the credential. Check the identifier and secret, that the API role is attached to it, and set an API access key if your API is IP-restricted.
  • A permission error for one view: the API role is missing that view's action. Add it to the role.
  • "Connector upstream must be https://" or a blocked address: the URL must start with https:// and use your server's public name.
  • A timeout: WHMCS took longer than 10 seconds. Large installations can be slow on the first load; try again, and check your server's load.
  • Finance numbers look doubled: the same sales are also entered by hand or counted by the Razorpay tile. See the note above.

Still stuck? Contact support with the view and the error shown.