Software Licences API
A licence product issues a key that your software checks with the guest check call. Each licence can be held to IP addresses, hostnames, install paths and versions, and billed per unit. See Software licences and Client IP limits. Most calls find the licence by its order (order_id).
Admin calls need Module access on the Servicelicense card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.
Admin calls
Section titled “Admin calls”plugin_get_pairs
Section titled “plugin_get_pairs”POST /api/admin/servicelicense/plugin_get_pairs
Lists the licence key plugins (key generators) that can be chosen for a licence.
Permission: Manage licenses (servicelicense.manage)
No parameters.
Returns: An object of plugin name => plugin name, such as {"Simple": "Simple"}.
update
Section titled “update”POST /api/admin/servicelicense/update
Changes a licence’s plugin, key and validation rules. Only the fields you send change.
Permission: Manage licenses (servicelicense.manage)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The licence’s order. |
plugin |
string | The key plugin (see plugin_get_pairs). |
license_key |
string | A new licence key. |
validate_ip |
boolean | Check the caller’s IP address against ips. |
validate_host |
boolean | Check the hostname against hosts. |
validate_path |
boolean | Check the install path against paths. |
validate_version |
boolean | Check the version against versions. |
ips |
string | Allowed IP addresses, one per line. Staff may set more than the server limit. |
hosts |
string | Allowed hostnames, one per line. |
paths |
string | Allowed install paths, one per line. |
versions |
string | Allowed versions, one per line. |
Returns: true.
Errors:
- Order ID is required (code 9999)
- Order not found (code 9999)
- Order is not activated (code 9999) when the order has no licence yet
Example
Request parameters:
{ "order_id": 21, "validate_host": true, "hosts": "example.com\nwww.example.com"}result:
truePOST /api/admin/servicelicense/reset
Clears a licence’s allowed IP addresses, hostnames, paths and versions, so the next check from a new installation can set them again.
Permission: Manage licenses (servicelicense.manage)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The licence’s order. |
Returns: true.
Errors:
- Order not found (code 9999)
- Order is not activated (code 9999)
Fires onBeforeServicelicenseReset and onAfterServicelicenseReset. Staff resets do not count as client IP changes.
ip_changes_clear
Section titled “ip_changes_clear”POST /api/admin/servicelicense/ip_changes_clear
Forgets which of the licence’s IP addresses checks have used, so the client can again remove them as free typo fixes.
Permission: Manage licenses (servicelicense.manage)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The licence’s order. |
Returns: true.
Written to the order’s history.
units_update
Section titled “units_update”POST /api/admin/servicelicense/units_update
Sets per-unit billing of a licence (such as per website): the billing switch, the unit count, or the answer to a held drop. The order’s price follows.
Permission: Manage licenses (servicelicense.manage)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The licence’s order. |
billing |
boolean | Bill per unit (on) or not (off). |
count |
integer | The unit count set by staff, 0 to 1,000,000. The next report from the software replaces it. |
held |
string | A big drop in the reported count waiting for staff: approve takes the new count; any other value refuses it. |
Returns: true.
Errors:
- The count must be a whole number from 0 to 1000000. (code 9999)
With billing on, the order’s price becomes the count times the unit price (at least the product’s minimum) a month, times the months of its period.
units_from_answers
Section titled “units_from_answers”POST /api/admin/servicelicense/units_from_answers
After a WHMCS import, sets the per-unit switch and count of a product’s licences from their imported order form answers. Licences whose switch staff already set are left alone.
Permission: Manage licenses (servicelicense.manage)
| Parameter | Type | Description |
|---|---|---|
product_id |
integer, required | The licence product. |
Returns: How many licences were set.
Errors:
- Product not found (code 9999)
- Set the answer field names first. (code 9999) when the product has no answer field names
ip_request_approve
Section titled “ip_request_approve”POST /api/admin/servicelicense/ip_request_approve
Approves the client’s waiting IP change request (add, remove or reset) and applies it.
Permission: Manage licenses (servicelicense.manage)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The licence’s order. |
Returns: true.
Errors:
- There is no IP address request waiting. (code 9999)
- The change no longer fits, so it was refused and the client was told: … (code 9999) when it can no longer be applied
The client is told (history, notification and email).
ip_request_refuse
Section titled “ip_request_refuse”POST /api/admin/servicelicense/ip_request_refuse
Refuses the client’s waiting IP change request.
Permission: Manage licenses (servicelicense.manage)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The licence’s order. |
reason |
string | Why, shown to the client. |
Returns: true.
Errors:
- There is no IP address request waiting. (code 9999)
The client is told.
check_log
Section titled “check_log”POST /api/admin/servicelicense/check_log
A licence’s latest checks, newest first.
Permission: Manage licenses (servicelicense.manage)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The licence’s order. |
limit |
integer | How many, 1 to 500. Default 50. |
Returns: A list of {host, ip, path, version, result, created_at}; result is Valid or the reason the check failed.
Example
Request parameters:
{ "order_id": 21, "limit": 1}result:
[ { "host": "example.com", "ip": "203.0.113.10", "path": "/var/www/app", "version": "2.4", "result": "Valid", "created_at": "2026-11-17 08:30:00" }]settings_get
Section titled “settings_get”POST /api/admin/servicelicense/settings_get
The licence settings: how long the check log is kept, the bans, and whether a usage report secret is set.
Permission: Manage licenses (servicelicense.manage)
No parameters.
Returns: log_days (0 keeps every check), bans (each {id, value, kind, notes, created_at}) and report_secret_set. The secret itself is never returned.
settings_update
Section titled “settings_update”POST /api/admin/servicelicense/settings_update
Saves how many days the licence check log keeps, and the usage report secret.
Permission: Manage licenses (servicelicense.manage)
| Parameter | Type | Description |
|---|---|---|
log_days |
integer, required | Days to keep, 0 to 3650; 0 keeps every check. |
report_secret |
string | The secret the licensed software signs its unit reports with. Empty keeps the saved one. |
Returns: true.
Errors:
- Keep the licence check log for 0 to 3650 days (0 keeps every check). (code 9999)
ban_add
Section titled “ban_add”POST /api/admin/servicelicense/ban_add
Bans a domain or IP address from every licence check.
Permission: Manage licenses (servicelicense.manage)
| Parameter | Type | Description |
|---|---|---|
value |
string, required | One domain or IP address. |
notes |
string | Why, for staff. |
Returns: The new ban’s id.
Errors:
- Enter one domain or IP address to ban. (code 9999)
- “…” is not a domain or an IP address. (code 9999)
- “…” is already banned. (code 9999)
A banned host or IP gets the check error "..." is banned from licence checks (code 1011).
ban_delete
Section titled “ban_delete”POST /api/admin/servicelicense/ban_delete
Lifts a licence ban.
Permission: Manage licenses (servicelicense.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The ban id (from settings_get). |
Returns: true.
Client calls
Section titled “Client calls”reset (client)
Section titled “reset (client)”POST /api/client/servicelicense/reset
Resets one of the client’s licences for a new installation: its allowed IP addresses, hostnames, paths and versions are cleared. It counts as one IP change and may wait for staff approval.
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The licence’s order (the client’s own, active). |
Returns: true (also when it waits for approval).
Errors:
- Order not found (code 9999)
- Order is not activated (code 9999)
- You have used your 2 IP changes for 30 days. The next one is free on … (code 9999)
- A change of these IP addresses is already waiting for approval. (code 9999)
- Only our staff can change these IP addresses. Please open a ticket. (code 9999)
Authorized users need the Manage services permission.
ip_add (client)
Section titled “ip_add (client)”POST /api/client/servicelicense/ip_add
Adds a server’s IP address to a licence whose product has a server limit. With staff approval on, it waits as a request.
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The licence’s order. |
ip |
string, required | One IP address. |
Returns: true.
Errors:
- This IP address is already on the list. (code 9999)
- This is not a single IP address: … (code 9999)
- This plan has no server limit, so its IP addresses are not added or removed one at a time. (code 9999)
- A change of these IP addresses is already waiting for approval. (code 9999)
Adding into a free place is free. Authorized users need the Manage services permission.
ip_remove (client)
Section titled “ip_remove (client)”POST /api/client/servicelicense/ip_remove
Removes an IP address from a licence. It counts as one IP change of the last 30 days, unless it was added in the last 24 hours and never used by a check.
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The licence’s order. |
ip |
string, required | The IP address to remove. |
Returns: true.
Errors:
- You have used your 2 IP changes for 30 days. The next one is free on … (code 9999)
- A change of these IP addresses is already waiting for approval. (code 9999)
Authorized users need the Manage services permission.
ip_request_withdraw (client)
Section titled “ip_request_withdraw (client)”POST /api/client/servicelicense/ip_request_withdraw
Withdraws the client’s IP change request that waits for staff approval.
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The licence’s order. |
Returns: true.
Errors:
- There is no IP address request waiting. (code 9999)
Authorized users need the Manage services permission.
Guest calls
Section titled “Guest calls”check (guest)
Section titled “check (guest)”POST /api/guest/servicelicense/check
The licence check your software makes: validates a licence key for the calling server’s IP address, hostname, install path and version. A rule list that is empty (or not validated) records the value checked, so the first installation fills it.
| Parameter | Type | Description |
|---|---|---|
license |
string, required | The licence key. |
host |
string, required | The hostname the software runs on. |
version |
string, required | The software version. |
path |
string, required | The install path. |
format |
integer | 2: a failed check is returned as a result with valid: false and the error, instead of an API error. |
Returns: licensed_to, created_at, expires_at, valid (true) and any extra fields the licence plugin adds. With format 2 also error and error_code (null when valid).
Errors:
- Invalid request. Parameters missing? (code 1000)
- License key is not present in call (code 1001)
- Host key is not present in call (code 1002, HTTP 401)
- Version key is not present in call (code 1003)
- Path key is not present in call (code 1004, HTTP 401)
- Your license key is invalid. (code 1005)
- License is not active (code 1006)
- Ip “203.0.113.10” is not allowed for this license (code 1007)
- Host “example.com” is not allowed for this license (code 1008)
- Version “2.4” is invalid for this license (code 1009)
- Software install path “/var/www/app” is invalid for this license (code 1010)
- “example.com” is banned from licence checks (code 1011)
- Rate limit exceeded. Please try again later. (code 429)
Every check of a known key is written to the licence’s check log with its result.
Example
Request parameters:
{ "license": "SIMPLE-1A2B3C4D5E", "host": "example.com", "version": "2.4", "path": "/var/www/app", "format": 2}result:
{ "licensed_to": "Jane Doe", "created_at": "2026-10-01 10:00:00", "expires_at": "2027-10-01 10:00:00", "valid": true, "error": null, "error_code": null}
