Purchased packages user-packages
Packages a tenant has bought: purchase, renew, change, buy add-ons and view usage.
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/user-packagesList purchased packages
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
tenant_ids | string | Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too. Filters only and does not switch the request scope; combined with tenant_id and other filters as an intersection. A tenant credential sending a non-empty value gets 403 |
ids | string | Only list these IDs: comma-separated positive integers, at most 200 after deduplication (same as the page_size limit; more, or a malformed value, returns 422); an empty value is the same as omitting it. Combined with other filters as an intersection; IDs you cannot see are silently left out. Pagination is unchanged: set page_size to at least the number of IDs to get them in one page |
package_id | integer | Only list purchased packages of this base package. |
package_ids | string | Filter by base packages: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection |
expire_within_days | integer | Only list purchased packages expiring within this many days (including already expired ones). |
name | string | Purchased package name or its base package name contains (the two are ORed; % and _ match literally). |
customized | boolean | true lists only purchased packages with individually edited quotas or not following the base package; false lists only those following it unchanged. |
/api/v2/user-packagesPurchase package
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
Request body application/json
| Field | Type | Description |
|---|---|---|
currency | string | Currency sold in (ISO 4217) = the user's account currency at purchase; the price_*_cents snapshot is in its minor units. |
dry_run | boolean | Quote only, do not save. |
duration | string | Duration: month/quarter/year (adds 1/3/12 months; at month end the last day of the target month is used). |
end_at | string | Expiry time of the purchased package. |
name | string | Name |
package_idRequired | integer | Base package id. |
/api/v2/user-packages/{id}Get purchased package
Authentication: User (some parameters admin only)
/api/v2/user-packages/{id}Update purchased package
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
backup_group_id | integer | Backup node group; null = none. |
bandwidth_mbps | integer | Bandwidth in Mbps, -1 = unlimited. |
cname_domain_id | integer | CNAME root domain; null = the package binds no lines. |
cname_hostname | string | Host record of the shared access name (used by sites and streams in per-package mode); empty = none yet. |
cname_mode | PackageCnameMode | CNAME mode. site = one access name per site or stream; package = sites and streams of a purchased package share one access name. |
connections | integer | Concurrent connections, -1 = unlimited. |
custom_cc_rule | boolean | Allows custom CC rules. |
domains | integer | Number of domains (each IP site counts as 1), -1 = unlimited. |
end_at | string | Expiry time of the purchased package. |
follow_base | boolean | Follows the base package; quota changes on the base package are synced here automatically (except fields in overrides). |
http_ports | integer | Number of non-standard HTTP/HTTPS ports (other than 80/443), -1 = unlimited. |
ip_num | integer | Number of selectable IPs ("My IPs"), -1 = unlimited. |
ip_pool_id | integer | IP pool used to provision IP sites (IP product line); null = not provisioned. |
ip_site | boolean | Opens IP sites: only when true can tenants create IP sites and pick new IPs; an IP pool is required while true. Turning it off keeps the pool, IP count, port count and picked IPs; existing packages are false (on upgrade, packages already using IP sites are set to true). |
ip_site_port | integer | IP-site ports: distinct ports across all IP sites of the package (80/443 included), -1 = unlimited; IP-site ports do not count toward non-standard ports. |
l2 | boolean | Includes tiered origin (tenant switch of the paid feature l2): tenants can turn on tiered origin for sites, and nodes use it, only while the master license l2 is active; existing packages are false (on upgrade, purchased packages of tenants already using tiered origin are set to true). |
name | string | Name |
node_group_id | integer | Primary node group; null = the package binds no lines. |
price_month_cents | integer | Monthly price locked at purchase. |
price_quarter_cents | integer | Quarterly price locked at purchase. |
price_year_cents | integer | Yearly price locked at purchase. |
region_id | integer | Region; null = the package binds no lines. |
reset_to_base | boolean | Admin only; true = reset quota fields to the base package values, clear overrides and follow again (cannot be combined with other fields). |
stream_ports | integer | Number of TCP/UDP forwarding ports, -1 = unlimited. |
traffic_gb | integer | Traffic in GB per billing cycle, -1 = unlimited. |
waf_enhanced | boolean | Includes WAF Enhanced (tenant switch of the paid feature waf_enhanced): tenants can use standard/strict levels, big screen, deep Bot, anti-tamper and so on only while the master license WAF Enhanced is not degraded; existing packages are false. |
websocket | boolean | Allows WebSocket. |
/api/v2/user-packages/{id}Delete purchased package
Authentication: User (some parameters admin only)
/api/v2/user-packages/{id}/change-quotesQuote package changes in batch
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
package_idRequired | integer[] | Candidate package ids; repeatable, at most 100. |
/api/v2/user-packages/{id}/changesChange package (upgrade or downgrade)
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
dry_run | boolean | Quote only, do not save. |
package_idRequired | integer | Base package id. |
/api/v2/user-packages/{id}/ipsMy IPs
Authentication: User (some parameters admin only)
/api/v2/user-packages/{id}/ipsSelect IPs
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
ip_idsRequired | integer[] | IDs of the pool IPs to select. |
/api/v2/user-packages/{id}/ips/{ip_id}Update note of selected IP
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
remarkRequired | string | Remark |
/api/v2/user-packages/{id}/ips/{ip_id}Remove selected IP
Authentication: User (some parameters admin only)
/api/v2/user-packages/{id}/node-groupsNode groups of a purchased package
Authentication: User (some parameters admin only)
/api/v2/user-packages/{id}/renewalsRenew purchased package
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
dry_run | boolean | Quote only, do not save. |
durationRequired | string | Duration: month/quarter/year (adds 1/3/12 months; at month end the last day of the target month is used). |
/api/v2/user-packages/{id}/upgradesList purchased add-ons
Authentication: User (some parameters admin only)
/api/v2/user-packages/{id}/upgradesBuy add-on
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
amount | integer | Number of units, default 1. |
dry_run | boolean | Quote only, do not save. |
restore_only | boolean | Undo only. Only cancels pending reductions that have not been renewed yet, free of charge; if they are fewer than amount it returns 409 instead of buying (restore_stale when already scheduled by a renewal, restore_done when already restored and nothing scheduled is pending). |
upgrade_idRequired | integer | Id of the add-on to buy. |
/api/v2/user-packages/{id}/upgrades/{upgrade_id}Reduce or remove purchased add-on
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
amount | integer | Number of units to reduce; omitted = remove the whole item. |
/api/v2/user-packages/{id}/usagePurchased package usage
Authentication: User (some parameters admin only)
Purchased packages object
| Field | Type | Description |
|---|---|---|
action | string | Operation: buy, renew, change or upgrade. |
added | integer[] | IDs of the pool IPs newly selected by this call. |
amount | integer | Number of units, default 1. |
amount_cents | integer | Positive = charged, negative = refunded to balance (downgrade), 0 = no charge (including admin operations). |
backup_group_id | integer | Backup node group; null = none. |
bandwidth_mbps | integer | Bandwidth in Mbps, -1 = unlimited. |
cert_auto | IpCertState | Platform IP certificate status. |
cname_domain_id | integer | CNAME root domain; null = the package binds no lines. |
cname_hostname | string | Host record of the shared access name (used by sites and streams in per-package mode); empty = none yet. |
cname_mode | PackageCnameMode | CNAME mode. site = one access name per site or stream; package = sites and streams of a purchased package share one access name. |
connections | integer | Concurrent connections, -1 = unlimited. |
created_at | string | Created at |
currency | string | Currency sold in (ISO 4217) = the user's account currency at purchase; the price_*_cents snapshot is in its minor units. |
custom_cc_rule | boolean | Allows custom CC rules. |
cycle_end | string | End of the current billing cycle. |
cycle_start | string | Start of the current billing cycle. |
domains | integer | Number of domains (each IP site counts as 1), -1 = unlimited. |
dry_run | boolean | Quote only, do not save. |
duration | string | Duration: month/quarter/year (adds 1/3/12 months; at month end the last day of the target month is used). |
enabled | boolean | Whether enabled |
end_at | string | Expiry time of the purchased package. |
feature_states | PackageFeatureStates | Whether the platform currently has each package paid feature enabled (license state is neither none nor degraded); a false item does not take effect for now even if the package includes it. |
follow_base | boolean | Follows the base package; quota changes on the base package are synced here automatically (except fields in overrides). |
http_ports | integer | Number of non-standard HTTP/HTTPS ports (other than 80/443), -1 = unlimited. |
id | integer | Record ID |
in_pool | boolean | Still in the package's current IP pool. |
ip | string | IP address. |
ip_idsRequired | integer[] | IDs of the pool IPs to select. |
ip_num | integer | Number of selectable IPs ("My IPs"), -1 = unlimited. |
ip_pool_id | integer | IP pool used to provision IP sites (IP product line); null = not provisioned. |
ip_site | boolean | Opens IP sites: only when true can tenants create IP sites and pick new IPs; an IP pool is required while true. Turning it off keeps the pool, IP count, port count and picked IPs; existing packages are false (on upgrade, packages already using IP sites are set to true). |
ip_site_port | integer | IP-site ports: distinct ports across all IP sites of the package (80/443 included), -1 = unlimited; IP-site ports do not count toward non-standard ports. |
items | UserPackageChangeQuote[] | Per-candidate quotes, in the order of the requested package_id (duplicates quoted once). |
l2 | boolean | Includes tiered origin (tenant switch of the paid feature l2): tenants can turn on tiered origin for sites, and nodes use it, only while the master license l2 is active; existing packages are false (on upgrade, purchased packages of tenants already using tiered origin are set to true). |
last_duration | string | Duration of the last purchase/renewal (pre-selected in the renewal dialog); null = provisioned by an admin with an explicit expiry, or a legacy row (nothing pre-selected). |
limit | integer | Number of IPs that can be selected; -1 means unlimited. |
limits | PackageLimits | Effective limits (package values plus add-ons; -1 = unlimited, 0/1 for feature items). |
name | string | Name |
node_group_id | integer | Primary node group; null = the package binds no lines. |
node_state | IpNodeState | State of the owning primary node: disabled if the node is disabled; otherwise online if a heartbeat arrived in the last 2 minutes, else offline. |
notice | string | Notice code after the operation: traffic_stats_unavailable = traffic statistics (ClickHouse) are down and this package is stopped (513) for exhausted traffic, so the restore is delayed until they recover. Absent when there is no notice. |
order_id | integer | Order id (when a charge or refund happened). |
overrides | PackageQuotaField[] | Quota fields edited individually by an admin that differ from the base package; skipped by automatic sync. |
package_id | integer | Base package id. |
package_name | string | Base package name (shown in package lists and orders). |
period | string | Price period used for proration when changing package. |
price_mode | string | Source of the locked price: base = base price; auto = converted at the exchange rate (renewals recompute at the current rate); manual = the fixed price set for this currency. |
price_month_cents | integer | Monthly price locked at purchase. |
price_quarter_cents | integer | Quarterly price locked at purchase. |
price_year_cents | integer | Yearly price locked at purchase. |
reason | ChangeQuoteReason | Why the change is not possible; same as the field error of a 422 from Change package (field/code/message). |
region | string | Name of the region it belongs to. |
region_id | integer | Region; null = the package binds no lines. |
remain_cycles | integer | Billing cycles charged when buying a traffic add-on (the current cycle counts as a full one, plus later cycles before expiry); traffic packs are not prorated by remaining days. |
remain_days | integer | Remaining days used for proration. |
remarkRequired | string | Remark |
requests | integer | Number of requests in this billing cycle (sealed hours plus a live count of hours not yet sealed). |
reset_to_base | boolean | Admin only; true = reset quota fields to the base package values, clear overrides and follow again (cannot be combined with other fields). |
restore_only | boolean | Undo only. Only cancels pending reductions that have not been renewed yet, free of charge; if they are fewer than amount it returns 409 instead of buying (restore_stale when already scheduled by a renewal, restore_done when already restored and nothing scheduled is pending). |
selected | integer | Number of IPs already selected. |
sites | object[] | IP sites in this package that bind it. |
start_at | string | Start time of the purchased package. |
status | string | expired = expired (the tenant's sites are suspended with 512; renewing restores them). |
stream_ports | integer | Number of TCP/UDP forwarding ports, -1 = unlimited. |
tenant_id | integer | Owner tenant (user) ID |
traffic_bytes | integer | Billable traffic used in this billing cycle (bytes, already multiplied by the compensation factor) — sealed hours plus a live count of hours not yet sealed, the same figure the over-quota stop uses. |
traffic_gb | integer | Traffic in GB per billing cycle, -1 = unlimited. |
traffic_limit_gb | integer | Effective traffic limit (GB, 1 GB = 1024^3 bytes, including add-ons); -1 = unlimited. |
updated_at | string | Updated at |
upgrade_idRequired | integer | Id of the add-on to buy. |
user_package | UserPackage | The purchased package after the operation. |
user_package_id | integer | Id of the purchased package this operation applied to (for a purchase, the newly created one; equals user_package.id). Absent for a dry run, which saves nothing. |
waf_enhanced | boolean | Includes WAF Enhanced (tenant switch of the paid feature waf_enhanced): tenants can use standard/strict levels, big screen, deep Bot, anti-tamper and so on only while the master license WAF Enhanced is not degraded; existing packages are false. |
websocket | boolean | Allows WebSocket. |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}