cdnca

API reference

/v1/admin/package-addons

6 operations

← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures

MethodPathSummaryAuth
GET/v1/admin/package-addons—Session
GET/v1/admin/package-addons/assignments—Session
GET/v1/admin/package-addons/bindings—Session
POST/v1/admin/package-addons/commands—Session
GET/v1/admin/package-addons/quote—Session
GET/v1/admin/package-addons/subscriptions—Session

Contract file：api/control-package-addons.openapi.yaml

Operation details

GET /v1/admin/package-addons

operationId
listPackageAddons
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

listPackageAddons Parameters
NameInTypeRequiredDescription
pagequeryintegerNo—
limitqueryintegerNo—

Responses

listPackageAddons Responses
StatusDescription
200Addon products ordered by descending display ID

Fields：total: integer page: integer limit: integer items?: array<Product>

401Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
403Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
defaultStable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list

GET /v1/admin/package-addons/assignments

operationId
listPackageAddonAssignments
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

listPackageAddonAssignments Parameters
NameInTypeRequiredDescription
pagequeryintegerNo—
limitqueryintegerNo—
userquerystringNoExact user UUID or display ID, or username, email, or phone substring
addon_idquerystring(uuid)No—

Responses

listPackageAddonAssignments Responses
StatusDescription
200Unrevoked assignments with immutable product snapshots

Fields：total: integer page: integer limit: integer items?: array<Assignment>

401Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
403Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
defaultStable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list

GET /v1/admin/package-addons/bindings

operationId
listPackageAddonBindings
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

Minimal product choices under the same addon administration permission.

Parameters

listPackageAddonBindings Parameters
NameInTypeRequiredDescription
pagequeryintegerNo—
limitqueryintegerNo—

Responses

listPackageAddonBindings Responses
StatusDescription
200Existing catalog product identity and name

Fields：total: integer page: integer limit: integer items?: array<object>

401Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
403Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
defaultStable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list

POST /v1/admin/package-addons/commands

operationId
commandPackageAddon
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

Writes are transactional with audit and actor/scope-bound idempotency receipts. Reusing a key with a different body returns package_addon_conflict. assignment.create is the administrator's free allocation (never charges). assignment.purchase (549) charges the owner tenant's balance at the quoted price on the owner's behalf (the administrator is the recorded actor), creates a paid add-on order, and adds to an existing assignment of the same add-on; a changed price returns package_addon_price_changed, an insufficient available balance returns insufficient_funds (422). Product deletion and assignment deletion retain history. WAF is fixed to one allocation and deletion is rejected while bound policies use it.

Parameters

commandPackageAddon Parameters
NameInTypeRequiredDescription
Idempotency-KeyheaderstringYes—
X-Request-IDheaderstringNoOptional correlation ID; the server generates one when absent or invalid.

Request body

application/json · Required：Yes

commandPackageAddon Request body
NameTypeRequiredDescription
actionstring: product.create / product.update / product.delete / assignment.create / assignment.purchase / assignment.update / assignment.deleteYes—
idstring(uuid)No—
expected_revisionintegerNo—
productProductFieldsNo—
addon_idstring(uuid)No—
owner_user_idstring(uuid)No—
subscription_idstring(uuid)No—
amountintegerNo—
expected_payable_minorintegerNoRequired by assignment.purchase; the payable amount shown to the operator

Responses

commandPackageAddon Responses
StatusDescription
200Mutation or exact replay result

Fields：id: string(uuid) revision: integer charged_minor: integer order?: Order

409Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
422Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
401Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
403Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
defaultStable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.

What to do on failure

  • 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list

GET /v1/admin/package-addons/quote

operationId
quotePackageAddonPurchase
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

Price of buying `amount` of an add-on for a sold package now (549). The monthly price is prorated over the remaining days (a started day counts whole, a month is 30 days, half-up to the cent), then the matching automatic package_addon discounts apply (tenant and the owner's user group). Includes the owner tenant's balance and available balance (balance minus active holds).

Parameters

quotePackageAddonPurchase Parameters
NameInTypeRequiredDescription
addon_idquerystring(uuid)Yes—
subscription_idquerystring(uuid)Yes—
amountqueryintegerNo—

Responses

quotePackageAddonPurchase Responses
StatusDescription
200Current purchase price

Fields：addon_id: string(uuid) subscription_id: string(uuid) tenant_scope_id: string(uuid) owner_user_id: string(uuid) amount: integer monthly_price_minor: integer remaining_days: integer subscription_ends_at: string(date-time) currency: string original_amount_minor: integer discount_amount_minor: integer payable_amount_minor: integer policies: array<AppliedPolicy> balance_minor: integer available_minor: integer merges: boolean

400Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
401Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
403Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
404Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
409Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
defaultStable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.

What to do on failure

  • 400 Fix the parameters or body per the field list; do not retry unchanged.
  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

GET /v1/admin/package-addons/subscriptions

operationId
listPackageAddonEligibleSubscriptions
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

listPackageAddonEligibleSubscriptions Parameters
NameInTypeRequiredDescription
pagequeryintegerNo—
limitqueryintegerNo—
userquerystringNoExact user UUID or display ID, or username, email, or phone substring
addon_idquerystring(uuid)No—

Responses

listPackageAddonEligibleSubscriptions Responses
StatusDescription
200Active subscription choices from the authoritative owner projection; addon filter excludes incompatible and duplicate allocations

Fields：total: integer page: integer limit: integer items?: array<SubscriptionOption>

401Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
403Stable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.
defaultStable error code. HTTP 400 invalid, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict/duplicate/WAF in use, 503 unavailable.

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list