Skip to content

Administration - Subscriptions

Manage subscription plans. Subscription plans define the features, quotas, and rate limits available to users.

For user subscription assignments, see Administration - Users › User Subscription Management.

Base path: /api/v1/admin

Method Endpoint Description
GET /api/v1/admin/subscription-plans List All Plans
POST /api/v1/admin/subscription-plans Create Plan
PUT /api/v1/admin/subscription-plans/{id} Update Plan
DELETE /api/v1/admin/subscription-plans/{id} Deactivate Plan

List All Plans

GET /api/v1/admin/subscription-plans

Requires Authentication - Scopes: admin:subscriptions:plans:read

Retrieve a list of all subscription plans for the current tenant, including inactive ones.

curl -X GET https://koldan.dixilang.com/api/v1/admin/subscription-plans \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/admin/subscription-plans",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())
SubscriptionPlanResponse
Status Description
200 OK Plans retrieved successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.

Create Plan

POST /api/v1/admin/subscription-plans

Requires Authentication - Scopes: admin:subscriptions:plans:write

Create a new subscription plan. Quotas and rate limits not explicitly defined will inherit tenant defaults.

CreateSubscriptionPlanRequest
Field Type Required Description
slug string Yes Unique URL-friendly identifier (lowercase alphanumeric and hyphens).
name string Yes Display name for the plan.
active boolean No Whether new users can subscribe to this plan. Default: true.
displayOrder integer No Ordering index for UI display. Default: 0.
quotas QuotaLimitsResponse No Quota limit overrides.
rateLimits RateLimitsResponse No Rate limit overrides.
permissions string[] No Permission scopes granted by this plan. 
curl -X POST https://koldan.dixilang.com/api/v1/admin/subscription-plans \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "pro-plan",
    "name": "Professional",
    "quotas": {
      "speech-service": {
        "maxConcurrentSessions": 5
      }
    },
    "permissions": ["speech:files:read", "speech:files:write"]
  }'
SubscriptionPlanResponse
Status Description
201 Created Plan created successfully.
400 Bad Request Validation error.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
409 Conflict A plan with the given slug already exists.

Update Plan

PUT /api/v1/admin/subscription-plans/{id}

Requires Authentication - Scopes: admin:subscriptions:plans:write

Update an existing subscription plan. Changes take effect immediately for all users assigned to this plan.

Path Parameters
Parameter Type Required Description
id string (UUID) Yes Unique identifier of the plan.
UpdateSubscriptionPlanRequest
Field Type Required Description
name string No New display name.
active boolean No Update availability status.
displayOrder integer No Update display order.
quotas QuotaLimitsResponse No Update quota overrides.
rateLimits RateLimitsResponse No Update rate limit overrides.
permissions string[] No Update granted permission scopes.
SubscriptionPlanResponse
Status Description
200 OK Plan updated successfully.
400 Bad Request Validation error.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Plan not found.

Deactivate Plan

DELETE /api/v1/admin/subscription-plans/{id}

Requires Authentication - Scopes: admin:subscriptions:plans:write

Deactivates a subscription plan. Existing subscribers remain on the plan, but no new users can be assigned to it.

Path Parameters
Parameter Type Required Description
id string (UUID) Yes Unique identifier of the plan.
Status Description
204 No Content Plan deactivated successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Plan not found.

User Subscription Assignment

Managing user subscriptions (get, assign, remove) is documented under Administration - Users › User Subscription Management.

Data Models

The data models used for subscription management are shared with the standard Subscriptions API. Refer to the primary documentation for field definitions and schemas: