This page is the short path. It does not explain why things work the way they do; the other pages in this section do that. Follow it top to bottom once, and use the linked pages afterwards when you need the detail behind a step.
You need three things before you start: a WHMCS 8.0 or newer installation you can administer, an Xtream AI Panel on version 2.1.2 or newer with the Panel API enabled (product upgrades and downgrades additionally need a panel updated on 2026-09-14 or later), and a Panel API key. If you do not have the key yet, step 2 shows where to get it.
1. Install the module
Download the latest release from the releases page on GitHub and unpack it. Two folders come out. Copy them into your WHMCS installation so that they land at these exact paths:
<whmcs root>/modules/addons/xtreamai/
<whmcs root>/modules/servers/xtreamai/Both folders must belong to the user that runs PHP for your WHMCS site, the same owner as the rest of the modules/ tree.
Then, in WHMCS admin, open System Settings → Addon Modules, find Xtream AI Panel, press Activate, and in the same row press Configure to tick the admin roles that may open the addon. Save.
That is the only manual installation you will ever do: from this point the addon updates itself with the Update now button on its dashboard. The full walkthrough, with the terminal and FTP variants, is in Install.
2. Get a Panel API key
On your Xtream AI Panel, log in and open Settings → Panel API Keys, then Create key. Give it a label you will recognise later, for example WHMCS, and tick the scopes.
| You are | Scopes to tick |
|---|---|
| The panel administrator | lines:read, lines:write, packages:read, bouquets:read, and for Sub-Reseller products also resellers:read, resellers:write, subresellers:write. |
| A reseller | lines:read, lines:write, packages:read, bouquets:read. Reseller keys cannot create sub-resellers or change connection counts; see Reseller vs Admin Keys. |
Copy the token as soon as it is shown. The panel displays it once; if you lose it, rotate the key from the same page.
3. Connect the panel to WHMCS
In WHMCS admin, open Addons → Xtream AI Panel, then the Panels tab, then Add Panel.
| Field | What to enter |
|---|---|
| Name | Any name, it only appears in WHMCS. |
| API URL | Your panel domain with the scheme and nothing else: https://panel.example.com. No trailing slash, no /panel-api/v1, and no panel folder such as /6390c2dde594413b. |
| API key | The token from step 2. |
| Key type | Admin or Reseller, matching the account that created the key. |
| Admin owner member_id | Admin keys only. The numeric id of the reseller account that will own every line this panel entry creates. |
| M3U URL and EPG URL | Optional. The playlist and guide URLs your customers will see on their service page, with {username} and {password} as placeholders. |
Press Test Connection before saving. The expected result is a green message naming the account behind the key. If you get anything else, the Troubleshooting page lists every message the test can return and what to do about it.
If your panel domain sits behind Cloudflare with the proxy enabled (orange cloud), the module's requests can be stopped by Cloudflare's browser challenge and the test fails. Either set the DNS record to DNS only (grey cloud) or add a WAF rule that skips the challenge for paths starting with
/panel-api/.
4. Create a Line product
This is the common product: each order creates one IPTV line on the panel.
- Open Products/Services → Products/Services, then Create a New Product.
- Under Details, set Product Type to Hosting Account, choose a product group, and give the product the name your customers will see. Save.
- Open the Module Settings tab and pick xtreamai in the Module Name dropdown. The page reloads with the module's options.
- Fill them in:
| Option | Value |
|---|---|
| Panel | The panel from step 3. |
| Package Type | Official. Choose Trial only for a trial product. |
| Package | The panel package this product sells. Its duration is what the line's expiry follows. |
| Bouquets | The bouquets every new line gets. Use the search box; on large catalogs it saves a lot of scrolling. |
| Account Type | Leave on Line (default). |
| Max Connections | 0 to use the package's own count, or a number from 1 to 100. Admin keys only. |
| Suspend action | Leave on Disable the line on the panel unless you want suspended services to keep streaming until their own expiry date. |
- Under Pricing, set a billing cycle that matches the package duration: a 1 month package on a Monthly cycle, a 3 months package on a Quarterly cycle, and so on. This keeps the panel expiry and the WHMCS due date in step at every renewal.
- Save the product.
To sell extra connections as an upsell instead of one product per connection count, add a configurable option named extra_connections to the product; the details are under Configure.
5. Create a Sub-Reseller product (optional)
A Sub-Reseller product creates a reseller account on the panel instead of a line, with a credit balance. It is not a separate product type in WHMCS: it is the same kind of product with one option changed.
- Create the product exactly as in step 4, points 1 to 3.
- In Module Settings, change Account Type from Line (default) to Sub-Reseller. Two more fields appear right below it, they are hidden while the type is Line:
- Credits, the balance the new account starts with. The same amount is added again on every renewal of the service.
- Sub-Reseller Member Group, the numeric id of the member group the new account is placed in. Read the id from the Group Permissions page of your panel, it is the first column of the list.
- Leave Package and Bouquets as they are; they are ignored for this account type.
- Save.
Sub-Reseller products need an Admin key on the panel entry. With a reseller key the order fails at creation and the module log says why.
6. Place a test order
Create a test client in WHMCS, order the Line product for it, mark the invoice as paid and, on the service page, press Create in the module commands. Within a second the page shows the line's username and password, and the same line appears on your panel with the note WHMCS:<service id>.
Log in to the WHMCS client area as that test client and open the service. The customer sees the username, the password, the expiry date, the connection count and, if you filled them in step 3, the M3U URL and the EPG URL with the credentials already substituted.
Repeat with the Sub-Reseller product if you created one. The new reseller shows up under Addons → Xtream AI Panel → Sub-Resellers with its credit balance.
7. What happens from here on
From this point WHMCS drives the line for you. The daily cron renews the panel expiry when an invoice is paid, disables the line when the service is suspended and enables it on unsuspend, and deletes it on termination. What each WHMCS event does on the panel is written out in Provisioning Modes.
On the service page in WHMCS admin, the module adds four buttons you will use most:
| Button | What it does |
|---|---|
| Refresh from panel | Reads the line as it is right now on the panel and shows its expiry and status. Read only. |
| Sync bouquets, notes & connections | Re-applies the product's bouquets, notes template and connection count to the line. |
| Set panel expiry to WHMCS next due date | Makes the panel expiry equal to the WHMCS due date. Admin key. |
| Set WHMCS next due date to panel expiry | The opposite direction. |
If you already have lines on the panel
Lines created before the module, or by another billing system, are not linked to any WHMCS service yet. The Bulk tools tab of the addon has four cards for this: Index reads every line of the panel, Link matches them to existing services, Sync re-applies the product configuration to every linked service, and Align panel expiry to WHMCS sets every line's expiry from its service's due date. Run them in that order; the page explaining each card is Bulk Tools.
Where to go next
- FAQ for the questions that come up most often.
- Configure for every field of the panel form and of the product options.
- Troubleshooting when a step fails with a message.