[FEATURE] Clarify and expose machine-readable VPS billing lifecycle controls

[coygeek]

Feature Description

Please clarify the billing lifecycle for API-created VPSs and expose machine-readable controls for the full lifecycle where possible.

In particular, it would help to make the relationship between these actions explicit:

• stopping a VPS
• deleting/destroying a VPS, if supported
• disabling auto-renewal
• cancelling a subscription, if supported
• refund/cancellation constraints
• what continues billing after a VPS is stopped

Problem Statement

The VPS API exposes:

POST /api/vps/v1/virtual-machines/{virtualMachineId}/stop

The billing API exposes subscription listing and auto-renewal enable/disable.

For agentic workflows, it is important to know whether stop is only a compute power-state action or whether it has any effect on billing. Automation needs a clear, machine-readable way to answer:

• Is this stopped VPS still billable?
• Which subscription owns this VM?
• Can auto-renewal be disabled safely?
• Is there an API-supported way to cancel or delete the billable resource?
• What exact action should an automation take when it wants to stop using a VPS and prevent future charges?

Proposed Solution

At minimum, improve API documentation around VPS billing lifecycle:

• explicitly state that stop does or does not affect billing
• link virtual_machine.subscription_id to the subscription endpoints
• document whether disabling auto-renewal is the supported API path for preventing future renewal
• document whether immediate cancellation or delete/destroy is available through API or only hPanel/support

If supported by the product model, add explicit endpoints such as:

DELETE /api/vps/v1/virtual-machines/{virtualMachineId}
POST /api/billing/v1/subscriptions/{subscriptionId}/cancel

If immediate cancellation is intentionally not available, a documented machine-readable reason would still be useful.

Use Cases

• Let agents report accurate billing risk before and after provisioning.
• Prevent users from assuming that a stopped VPS is no longer billable.
• Build safe cleanup flows for short-lived VPS automation.
• Reconcile VM inventory with billing subscriptions without dashboard inspection.

Additional Context

The current VPS.V1.VirtualMachine.VirtualMachineResource includes subscription_id, which is a good foundation. This request is about making the lifecycle semantics and available billing controls explicit enough for automation to behave safely.

Are you willing to contribute?

• Yes, I'd like to implement this feature
• Yes, but I need guidance
• No, but I'm available for testing
• No