Version 2.4.8 · latest

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.

PackagesAuthentication: User (some parameters admin only)17 endpoints

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.

GET/api/v2/user-packagesList purchased packages

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
tenant_idsstring 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
idsstring 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_idinteger Only list purchased packages of this base package.
package_idsstring 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_daysinteger Only list purchased packages expiring within this many days (including already expired ones).
namestring Purchased package name or its base package name contains (the two are ORed; % and _ match literally).
customizedboolean true lists only purchased packages with individually edited quotas or not following the base package; false lists only those following it unchanged.
POST/api/v2/user-packagesPurchase package

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger 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

FieldTypeDescription
currencystring Currency sold in (ISO 4217) = the user's account currency at purchase; the price_*_cents snapshot is in its minor units.
dry_runboolean Quote only, do not save.
durationstring Duration: month/quarter/year (adds 1/3/12 months; at month end the last day of the target month is used).
Values ["month","quarter","year"]
end_atstring Expiry time of the purchased package.
namestring Name
package_idRequiredinteger Base package id.
GET/api/v2/user-packages/{id}Get purchased package

Authentication: User (some parameters admin only)

PUT/api/v2/user-packages/{id}Update purchased package

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
backup_group_idinteger Backup node group; null = none.
bandwidth_mbpsinteger Bandwidth in Mbps, -1 = unlimited.
cname_domain_idinteger CNAME root domain; null = the package binds no lines.
cname_hostnamestring Host record of the shared access name (used by sites and streams in per-package mode); empty = none yet.
cname_modePackageCnameMode CNAME mode. site = one access name per site or stream; package = sites and streams of a purchased package share one access name.
Values ["site","package"]
connectionsinteger Concurrent connections, -1 = unlimited.
custom_cc_ruleboolean Allows custom CC rules.
domainsinteger Number of domains (each IP site counts as 1), -1 = unlimited.
end_atstring Expiry time of the purchased package.
follow_baseboolean Follows the base package; quota changes on the base package are synced here automatically (except fields in overrides).
http_portsinteger Number of non-standard HTTP/HTTPS ports (other than 80/443), -1 = unlimited.
ip_numinteger Number of selectable IPs ("My IPs"), -1 = unlimited.
ip_pool_idinteger IP pool used to provision IP sites (IP product line); null = not provisioned.
ip_siteboolean 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_portinteger 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.
l2boolean 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).
namestring Name
node_group_idinteger Primary node group; null = the package binds no lines.
price_month_centsinteger Monthly price locked at purchase.
price_quarter_centsinteger Quarterly price locked at purchase.
price_year_centsinteger Yearly price locked at purchase.
region_idinteger Region; null = the package binds no lines.
reset_to_baseboolean Admin only; true = reset quota fields to the base package values, clear overrides and follow again (cannot be combined with other fields).
stream_portsinteger Number of TCP/UDP forwarding ports, -1 = unlimited.
traffic_gbinteger Traffic in GB per billing cycle, -1 = unlimited.
waf_enhancedboolean 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.
websocketboolean Allows WebSocket.
DELETE/api/v2/user-packages/{id}Delete purchased package

Authentication: User (some parameters admin only)

GET/api/v2/user-packages/{id}/change-quotesQuote package changes in batch

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
package_idRequiredinteger[] Candidate package ids; repeatable, at most 100.
POST/api/v2/user-packages/{id}/changesChange package (upgrade or downgrade)

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
dry_runboolean Quote only, do not save.
package_idRequiredinteger Base package id.
GET/api/v2/user-packages/{id}/ipsMy IPs

Authentication: User (some parameters admin only)

POST/api/v2/user-packages/{id}/ipsSelect IPs

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
ip_idsRequiredinteger[] IDs of the pool IPs to select.
PUT/api/v2/user-packages/{id}/ips/{ip_id}Update note of selected IP

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
remarkRequiredstring Remark
DELETE/api/v2/user-packages/{id}/ips/{ip_id}Remove selected IP

Authentication: User (some parameters admin only)

GET/api/v2/user-packages/{id}/node-groupsNode groups of a purchased package

Authentication: User (some parameters admin only)

POST/api/v2/user-packages/{id}/renewalsRenew purchased package

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
dry_runboolean Quote only, do not save.
durationRequiredstring Duration: month/quarter/year (adds 1/3/12 months; at month end the last day of the target month is used).
Values ["month","quarter","year"]
GET/api/v2/user-packages/{id}/upgradesList purchased add-ons

Authentication: User (some parameters admin only)

POST/api/v2/user-packages/{id}/upgradesBuy add-on

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
amountinteger Number of units, default 1.
dry_runboolean Quote only, do not save.
restore_onlyboolean 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_idRequiredinteger Id of the add-on to buy.
DELETE/api/v2/user-packages/{id}/upgrades/{upgrade_id}Reduce or remove purchased add-on

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
amountinteger Number of units to reduce; omitted = remove the whole item.
GET/api/v2/user-packages/{id}/usagePurchased package usage

Authentication: User (some parameters admin only)

Purchased packages object

FieldTypeDescription
actionstring Operation: buy, renew, change or upgrade.
Values ["buy","renew","change","upgrade"]
addedinteger[] IDs of the pool IPs newly selected by this call.
amountinteger Number of units, default 1.
amount_centsinteger Positive = charged, negative = refunded to balance (downgrade), 0 = no charge (including admin operations).
backup_group_idinteger Backup node group; null = none.
bandwidth_mbpsinteger Bandwidth in Mbps, -1 = unlimited.
cert_autoIpCertState Platform IP certificate status.
cname_domain_idinteger CNAME root domain; null = the package binds no lines.
cname_hostnamestring Host record of the shared access name (used by sites and streams in per-package mode); empty = none yet.
cname_modePackageCnameMode CNAME mode. site = one access name per site or stream; package = sites and streams of a purchased package share one access name.
Values ["site","package"]
connectionsinteger Concurrent connections, -1 = unlimited.
created_atstring Created at
read-only
currencystring Currency sold in (ISO 4217) = the user's account currency at purchase; the price_*_cents snapshot is in its minor units.
custom_cc_ruleboolean Allows custom CC rules.
cycle_endstring End of the current billing cycle.
cycle_startstring Start of the current billing cycle.
domainsinteger Number of domains (each IP site counts as 1), -1 = unlimited.
dry_runboolean Quote only, do not save.
durationstring Duration: month/quarter/year (adds 1/3/12 months; at month end the last day of the target month is used).
Values ["month","quarter","year"]
enabledboolean Whether enabled
end_atstring Expiry time of the purchased package.
feature_statesPackageFeatureStates 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_baseboolean Follows the base package; quota changes on the base package are synced here automatically (except fields in overrides).
read-only
http_portsinteger Number of non-standard HTTP/HTTPS ports (other than 80/443), -1 = unlimited.
idinteger Record ID
read-only
in_poolboolean Still in the package's current IP pool.
ipstring IP address.
ip_idsRequiredinteger[] IDs of the pool IPs to select.
ip_numinteger Number of selectable IPs ("My IPs"), -1 = unlimited.
ip_pool_idinteger IP pool used to provision IP sites (IP product line); null = not provisioned.
ip_siteboolean 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_portinteger 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.
itemsUserPackageChangeQuote[] Per-candidate quotes, in the order of the requested package_id (duplicates quoted once).
l2boolean 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_durationstring 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).
read-onlyValues ["month","quarter","year"]
limitinteger Number of IPs that can be selected; -1 means unlimited.
limitsPackageLimits Effective limits (package values plus add-ons; -1 = unlimited, 0/1 for feature items).
namestring Name
node_group_idinteger Primary node group; null = the package binds no lines.
node_stateIpNodeState 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.
Values ["online","offline","disabled"]
noticestring 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.
Values ["traffic_stats_unavailable"]
order_idinteger Order id (when a charge or refund happened).
overridesPackageQuotaField[] Quota fields edited individually by an admin that differ from the base package; skipped by automatic sync.
read-only
package_idinteger Base package id.
package_namestring Base package name (shown in package lists and orders).
read-only
periodstring Price period used for proration when changing package.
Values ["month","quarter","year"]
price_modestring 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.
Values ["base","auto","manual"]
price_month_centsinteger Monthly price locked at purchase.
price_quarter_centsinteger Quarterly price locked at purchase.
price_year_centsinteger Yearly price locked at purchase.
reasonChangeQuoteReason Why the change is not possible; same as the field error of a 422 from Change package (field/code/message).
regionstring Name of the region it belongs to.
region_idinteger Region; null = the package binds no lines.
remain_cyclesinteger 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_daysinteger Remaining days used for proration.
remarkRequiredstring Remark
requestsinteger Number of requests in this billing cycle (sealed hours plus a live count of hours not yet sealed).
reset_to_baseboolean Admin only; true = reset quota fields to the base package values, clear overrides and follow again (cannot be combined with other fields).
restore_onlyboolean 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).
selectedinteger Number of IPs already selected.
sitesobject[] IP sites in this package that bind it.
start_atstring Start time of the purchased package.
statusstring expired = expired (the tenant's sites are suspended with 512; renewing restores them).
Values ["active","expired"]
stream_portsinteger Number of TCP/UDP forwarding ports, -1 = unlimited.
tenant_idinteger Owner tenant (user) ID
read-only
traffic_bytesinteger 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_gbinteger Traffic in GB per billing cycle, -1 = unlimited.
traffic_limit_gbinteger Effective traffic limit (GB, 1 GB = 1024^3 bytes, including add-ons); -1 = unlimited.
updated_atstring Updated at
read-only
upgrade_idRequiredinteger Id of the add-on to buy.
user_packageUserPackage The purchased package after the operation.
user_package_idinteger 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_enhancedboolean 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.
websocketboolean 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.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "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"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command