Billing Cycle and Usage Control

Platform Edition is billed at the account (UIN) level: after purchasing one Platform Edition package, the resource usage of all environments under the account is metered and deducted from the package credits. This document explains how to query environment usage, control environment status, and the division of responsibilities between the platform and you, helping you implement "billing cycle + usage" management in your own business.

Responsibility Boundary Between the Platform and You

CloudBase provides the metering facts and execution APIs, while billing cycle rules, quota judgment, and disposal policies are implemented by you:

Layer	Responsible party	Capabilities provided
Metering	CloudBase	Usage statistics, querying environment usage by time range
Execution	CloudBase	Suspend / resume / destroy APIs (controlled + audited)
Notification	CloudBase	Usage change event callbacks (not yet available)
Billing cycle	You (customer)	Billing cycle rules (period, quota reset / rollover)
Quota	You (customer)	Quota system (credits / traffic / requests, etc.)
Policy	You (customer)	Threshold judgment, alerts, suspend / resume / destroy decisions

Why the platform does not implement billing cycles

Every customer's business model (free trial, pay-as-you-go, prepaid, enterprise contracts) differs greatly, and the combination space of billing cycle and quota policies is huge (auto-renewal, suspend with retention, downgrade on expiry, overage pay-as-you-go, overdraft, etc.). CloudBase does not "make decisions" on policies for customers. Instead, it provides atomic capabilities that you combine according to your own business rules for maximum flexibility.

Querying Usage

The platform provides environment-level usage query capabilities, supporting queries of credit usage by specified time range and environment ID, which can be used for billing cycle settlement, cost analysis, and quota judgment.

Call the query API (such as DescribeEnvUsage) with the time range and environment ID:

const result = await tcbClient.DescribeEnvUsage({
  EnvId: userEnvId,
  StartTime: "2026-08-01 00:00:00", // time range
  EndTime: "2026-08-31 23:59:59",
});
// result contains the credit usage details of the environment in the time range

Usage suggestions:

• Billing cycle settlement: query cumulative usage by time range at the end of each billing cycle for reconciliation and settlement
• Cost analysis: query usage by environment and time period to identify high-consumption environments
• Quota judgment: compare the query results with the quota thresholds you set, and trigger subsequent disposal

Controlling Environment Status

The platform provides environment-level status control APIs. You can suspend / resume / destroy a single environment according to your business strategy:

Operation	Description
Suspend	The environment enters a suspended state (with the same effect as isolation); running services stop, data is retained, credits continue to be consumed, and it can be resumed on demand
Resume	Restore a suspended environment to a normal usable state
Destroy	Delete the environment (data will be cleared; operate with caution)

// Suspend an environment (example: triggered when quota is exhausted)
await tcbClient.SuspendEnv({ EnvId: userEnvId });

// Resume an environment (example: after the customer renews)
await tcbClient.ResumeEnv({ EnvId: userEnvId });

Status control notes

• Suspend / resume only supports manual triggering; it cannot be called when the account is in a system suspension state (overrun service suspension / expiry isolation).
• After suspension, data is retained and credits continue to be consumed.
• Destruction clears data; please confirm there are no business dependencies before operating.

Usage Notification Methods

To determine "which environments need disposal", there are two usage notification methods:

Method 1: Scheduled polling

You traverse the environment list with scheduled tasks, query usage by each billing cycle, compare with quotas, and issue disposal:

Suitable for scenarios with a small number of environments. When there are many environments, full polling generates a large number of API calls (number of environments × polling frequency).

Method 2: Event callbacks (not yet available)

CloudBase provides usage change event callbacks: when a usage change is detected, CloudBase proactively calls back your system, so you only need to process environments with changes, avoiding scheduled traversal of all environments. This capability is not yet available; use Method 1 (scheduled polling) for now.

Method 2 (event callbacks) is not yet available; use Method 1 (scheduled polling) for now.

Recommended Implementation Flow

1. Purchase the package and create environments: see Purchase and Initialization and Create Environments
2. Deliver API Keys: see Manage API Keys
3. Build a billing cycle engine: define billing cycle rules (period, quota reset / rollover) and a quota system (credits / traffic / requests)
4. Integrate usage notification: obtain usage for each environment via scheduled polling (event callbacks are not yet available)
5. Implement disposal policies: compare usage with quotas and trigger suspend / resume / destroy / alert actions

Next Steps

• Learn about environment lifecycle management: Create Environments
• Learn about the package and billing model: Platform Edition Overview