Skip to content

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.

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"}.

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:

true

POST /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.

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.

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.

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

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).

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.

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"
}
]

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.

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)

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).

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.

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.

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.

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.

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.

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
}