WHMCS Module FAQ

Each answer is deliberately short and links to the page with the full detail. If your question is not here, the Troubleshooting page covers error messages, and the support team can be reached from your client area.

Setting up products

When I create a product I only see line packages. Where is the option for a credits or sub-reseller product? It is inside the same product. Open the product's Module Settings tab and change Account Type from Line (default) to Sub-Reseller. The Credits and Sub-Reseller Member Group fields are hidden until you switch that dropdown, and they appear right below it once you do. Package and Bouquets are ignored for that account type. Step by step in the Quickstart.

Do I need an admin key or is a reseller key enough? For Line products a reseller key is enough. Sub-Reseller products, connection counts that differ from the package, product upgrades and downgrades, and the expiry buttons all need an admin key. The complete matrix is in Reseller vs Admin Keys.

What do I put in the API URL field? Your panel domain with the scheme and nothing else: https://panel.example.com. No trailing slash, no /panel-api/v1 and no panel folder. With the folder in the URL most actions still work, but the line status check on the service page answers 404.

Where do I find the member group id for a Sub-Reseller product? On your panel, open the Group Permissions page. The id is the first column of the list. The group must exist on the panel; with a wrong id the order fails with The panel rejected the request values.

Can one product have several connection counts? Yes. Attach a configurable option named extra_connections (added on top of the package count) or max_connections (replaces it) and let the customer choose at checkout. This needs an admin key. See Configure.

Can my customers choose their own username? Yes, on Line and Sub-Reseller products. Set the product's Customer username option to Customer types it in the "Line username" or "Reseller username" custom field and add a WHMCS custom field to that product: Line username on a Line product, Reseller username on a Sub-Reseller one (Text Box, Show on Order Form ticked, Required if every order must carry one). The customer types the username at checkout, the module validates it (3 to 32 letters, digits, dashes or underscores), checks the panel and creates the account with it, generating the password as usual. The check runs before payment and again when WHMCS creates the service, and the module never attaches an existing line to a customer order, so nobody can take over another customer's line. On a Sub-Reseller product the lookup against the panel needs an Admin key on the panel entry: with a Reseller key the cart accepts the name and the panel refuses a duplicate when the account is created. Full setup in Configure.

Can my customers choose their own password too? Yes, on Line and Sub-Reseller products, from module 1.10.0. Set the product's Customer password option to Customer types it in the "Panel password" custom field and add a WHMCS custom field to that product named Panel password (type Password is the recommended one, Show on Order Form ticked, Required only if you want to force it). The module accepts 8 to 32 characters with no spaces and none of % & ? # / \ + " < >, and refuses anything else in the cart and again when it creates the service. Once the account exists the module empties that custom field on the service and the password stays only in the service's password field, but until then the value sits in the custom field, so keep the field type on Password and check that your WHMCS Order Confirmation email does not print custom fields. Full setup in Configure.

Does the order form check the username before the customer pays? Yes, from module 1.9.1. When the customer adds one of your products to the cart, and again on the checkout page, the module checks the value in the Line username field of a Line product with the Customer username option on, the value in the Reseller username field of a Sub-Reseller product with Customer username on (module 1.10.0 and later), and the value in the Reseller username field of a Credit top-up product. From module 1.10.0 it also checks the Panel password field of a Line or Sub-Reseller product with Customer password on. The accepted names can sit in either half of a WHMCS field name, and a product that carries a single custom field needs no special name at all (module 1.9.4 and later). A username that is already used by another line, one that no account on the panel carries, or one that belongs to a panel administrator stops the order with a clear message before any payment, and so does a password that breaks the rules. Two things the cart does not cover: a field left empty, and — with Top-up scope set to the client's own Sub-Reseller accounts — a customer who is not signed in, because the cart has nothing to compare the value against; in both cases the username is checked when the service is created. The messages are listed in Troubleshooting.

Which billing cycle should the product have? The one that matches the package duration: a 1 month package on Monthly, a 3 months package on Quarterly, a 12 months package on Annually. Mismatched cycles make the panel expiry and the WHMCS due date drift at every renewal.

My trial product costs nothing and the order stays Pending. Why? A 0.00 order never raises an invoice, so the setup timing as soon as the first payment is received never fires and the order waits in Pending until an admin accepts it. Open the product's Module Settings tab and set the setup timing to as soon as an order is placed for free and trial products. For paid products, leave it on as soon as the first payment is received: the line is provisioned as soon as the invoice is paid. If you cancel such a Pending order, WHMCS can list it with an outstanding cancellation request, which is WHMCS's own order bookkeeping and not a module error. More in Troubleshooting and When the setup runs.

Credits and sub-resellers

Does the module handle reseller credit refills? Yes, in three ways. Through a Credit top-up product: the customer orders credits from your website and the module adds them to the Sub-Reseller account they already have on the same panel. Through a renewal: the Credits value of a Sub-Reseller product is added to the account on creation and again on every renewal of that service. Manually: in Addons → Xtream AI Panel → Sub-Resellers, each account has a field where you type a positive or negative amount, an optional reason, and press Apply. All three need an admin key. Details in Sub-Reseller mode and Credit top-up mode.

My resellers buy credits from my website. How do I stop each order from creating a new account? Sell them a Credit top-up (existing Sub-Reseller) product. When the order is paid, the module looks for the client's active Sub-Reseller services on the same panel, takes the account they are linked to, and adds the credits there instead of creating anything new. Add a required custom field named Reseller username to the product: the customer types the panel account and the module finds it on the panel, even when that account never went through WHMCS. A top-up product needs an admin key on the panel entry, like every Sub-Reseller feature. Step by step in Provisioning Modes.

Can a top-up go to an account that was not created through WHMCS? Yes, with the default Top-up scope of Any reseller on the panel. Add a required custom field named Reseller username to the top-up product and the customer types the panel account at checkout: the module looks that username up on the panel and credits it, even when the account was created there by hand and never went through WHMCS. The top-up service stays linked to the account it credited, so its renewals keep topping it up. If the client already has a Sub-Reseller service in WHMCS linked to that account, the custom field is not needed: run Bulk tools → Link for the panel once and the module credits the linked account. If the username does not exist on the panel either, the order stops with The reseller username "<value>" was not found on this panel.

Can a customer send credits to an account that is not theirs? By default, yes. With a Reseller username custom field on the product and Top-up scope left at Any reseller on the panel, the customer can type the username of any reseller on the panel and the credits go there, whether or not WHMCS created that account. The credits are paid for, so the worst outcome is a gift to another account. If you want top-ups limited to the customer's own accounts, set Top-up scope to Only this client's linked Sub-Reseller accounts: the module then accepts only usernames that match a Sub-Reseller service of the same client linked on that panel and refuses anything else without querying the panel. In either scope a username that belongs to a panel administrator is refused, because an administrator account holds no reseller credit balance. Both scopes are described in the Top-up scope row of Configure.

Can a reseller key create sub-resellers? No. The panel only issues the resellers:* scopes to admin keys, so a reseller cannot create other resellers through WHMCS. This is a rule of the panel, not of the module.

What happens to a sub-reseller when the WHMCS service is suspended or terminated? Today nothing on the panel: the module records the state in WHMCS and leaves the account as it is. To disable a sub-reseller, do it from your panel. The reasons are explained in Provisioning Modes.

Lines and daily operation

Does suspending a service in WHMCS disable the line? By default yes, and unsuspending enables it again. If you prefer suspended services to keep streaming until the line's own expiry date, set the product's Suspend action to Leave the line untouched, let it expire.

Does terminating a service delete the line? Yes. Terminate removes the line from the panel. If you want to keep the line, suspend instead of terminating.

A renewal reset the extra connections of a line. Why? Update the module. The panel's renewal applies the package's connection count, and from module 1.5.3 the renewal re-applies the product's connection count right after, on admin keys. Older module versions do not.

Can a customer upgrade or downgrade between two of my products? Yes, with an admin key and a panel updated on 2026-09-14 or later. The module moves the line to the new package in one call, keeping its expiry date. On a reseller key the panel refuses the package change. See the ChangePackage section of Provisioning Modes.

Can I change a line's password from WHMCS? Yes. The WHMCS password change is sent to the panel; if the customer typed a password the module keeps it, otherwise it generates one with your credential settings.

What does my customer see in the client area? The username, the password, the expiry date, the connection count (with the line's maximum, such as 1 / 2, from module 1.14.0), and the M3U and EPG URLs you configured on the panel entry, with the credentials already filled in. Nothing else: no panel links, no reseller data.

Can I stop the module from writing into the line notes? Yes. In Addons → Xtream AI Panel → General Settings, inside the Line Notes Template card, the Write notes switch is on Yes by default. Left on Yes, the template (WHMCS:{service_id} by default) is written on every new line and Sub-Reseller account and written again by Sync bouquets, notes & connections, by Sync services in Bulk tools and by a product change. Set it to No and the module never writes to the notes of a line or a Sub-Reseller account: nothing is written when the account is created, synced or moved to another package, and the notes already on the panel are left exactly as they are. The switch belongs to the whole WHMCS installation, not to a single product. Two consequences of No: Link existing services in Bulk Tools can then match services by username only, because the lines created after the change carry no WHMCS:<service id> tag to read, and pressing Sync bouquets, notes & connections on a service whose product has no bouquets and no connection count to push leaves Nothing to push in Last action instead of Synced notes. The addon's help text for the switch reads: "When No, the module never writes to the notes of a line or a Sub-Reseller account: nothing is written when the account is created, synced or moved to another package, and existing notes are left as they are. Bulk tools then link services by username only."

A detail about the notes on a freshly created line: the panel prepends Created via panel-api | to them, because it is the panel that marks the lines its API created, not the module. That prefix is not part of the template, and the first sync leaves the notes exactly as the template says. Sub-Reseller accounts do not get that prefix. With Write notes set to No the line is created without notes at all, so it carries neither the template nor the prefix, and a Credit top-up writes no notes either, because it creates no account.

Existing lines and bulk tools

I already have lines on the panel. How do I attach them to WHMCS services? Use the Bulk tools tab of the addon in this order: Index reads every line of the panel, Link matches them to your WHMCS services (first by the WHMCS:<service id> tag in the line notes, then by username), Sync re-applies the product configuration to every linked service, and Align panel expiry to WHMCS sets every line's expiry from its due date. The page is Bulk Tools. For a single service you do not need the bulk cards: type the panel username in the service's Username field, save, and press Link existing line on the service page.

I have customers with lines created before WHMCS. How do I make WHMCS renew those lines? Link each service to its line once. For one service, create or accept the WHMCS service without running the module's Create (uncheck Run Module Create when you accept the order), type the panel username in the service's Username field, press Save Changes and then press Link existing line on the service page: the module links that line, stores its username and password for the client area card and leaves both the panel and the WHMCS next due date untouched. Renew, Sync, Refresh and Change Password work on that line from then on. For many services at once, run Index and Link in Bulk Tools. To align the dates, use the two expiry buttons on the service page or the Align panel expiry to WHMCS card.

Do I need to run Index before Align panel expiry to WHMCS? Only if some services are not linked yet: Align runs over the services that already show a panel line on their service page, and unlinked services are simply left out. Lines that existed before the module need Index and Link once. The order of the cards is explained in Bulk Tools.

Does Sync change the expiry date? No. Sync pushes bouquets, notes and connection count only; the expiry is handled by the two expiry buttons on the service page and by the Align panel expiry to WHMCS card. See Bulk Tools.

Updates, keys and connectivity

How do I update the module? From the addon dashboard: when a new version exists a card shows it with an Update now button. The module downloads the release, verifies it, swaps the two folders and rolls back on any failure. Manual installation is only needed the first time. If the cart keeps accepting a username it should refuse right after an update, your hosting may still be serving the previous PHP files for a while; see Troubleshooting. Full details in Install.

I run the module on more than one WHMCS installation. Do I have to update each one? Yes. Every installation has its own copy of the module, so Update now, the version on the Dashboard and the Module Log all belong to the installation you are logged into. Update each one from its own Dashboard, and when you test something, place the order and read the Module Log in the same installation: the other ones keep running the files they have until you update them too.

The cart shows a message that is not in these docs, for example API CONNECTION ERROR!. Where does it come from? Not from this module, which never prints that text. It is left over from a module of a previous panel still installed in your WHMCS: an addon that is still active, or a file in the includes/hooks folder. Deactivate the leftover addon under System Settings → Addon Modules (older layouts: Setup → Addon Modules) and remove those files, then test the cart again. See Troubleshooting.

Test Connection fails or every call returns 403 since I moved the panel domain to Cloudflare. Cloudflare's proxy (orange cloud) answers the module's requests with a browser challenge that a server cannot pass. Either set the panel's DNS record to DNS only (grey cloud), or add a WAF rule in Cloudflare that skips the challenge for paths starting with /panel-api/. Nothing needs to change in the module. The other Test Connection failures are listed in Troubleshooting.

I revoked a key by mistake. What now? Create a new key on the panel with the same scopes, edit the panel entry in the addon, paste the new token and press Test Connection. Existing services keep working; only the token changed.

Where are the module's logs? In Addons → Xtream AI Panel → Module Logs, a view of WHMCS's own module log filtered to this module. Every panel call is recorded; tokens never appear there, so the log is safe to share with support.

Is the module free? Yes. It is open source under the MIT license, published at github.com/Xtream-AI/whmcs-xtreamai. Only the panel license is paid.

Which WHMCS and panel versions do I need? WHMCS 8.0 or newer, PHP 7.2 or newer, and an Xtream AI Panel on 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.