Skip to content

Change a VPS billing cycle

POST /api/v2/vps/{id}/actions/billing-cycle

Change how often a VPS is billed, for example from monthly to annually. List the cycles and their prices first with GET /api/v2/vps/{id}/actions/billing-cycle. Send dryRun: true to preview the price of the new cycle without changing anything. wouldBlock in the preview says whether an open invoice stops the change.

Without dryRun the cycle changes at once. The VPS keeps running. The new price applies from the next renewal. When an unpaid renewal invoice or an open order exists for the VPS, the call returns 409 existing_invoice_blocking. Either pay that invoice first or send cancelExistingInvoice: true. Hostup then cancels the open renewal invoice and creates a new one for the new cycle. It comes back as renewalInvoice. An invoice that cannot be cancelled and replaced automatically, for example one that also bills other services and has credit applied, returns 409 existing_invoice_not_cancellable instead. Pay it first; it is named in existingInvoice. A change that is already scheduled for the VPS returns 409 scheduled_change_in_progress.

Authentication: An API key with the scope write:billing. About keys and scopes

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Body

billingCyclestringrequired
The new billing cycle. One of monthly, quarterly, semiannually, annually, biennially, triennially.
dryRunboolean
Preview the change without making it. Default false.
cancelExistingInvoiceboolean
Cancel an unpaid renewal invoice and create a new one for the new cycle. Default false.

Example

POST /api/v2/vps/{id}/actions/billing-cycle
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/billing-cycle" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"billingCycle": "annually",
"dryRun": true
}'

Responses

200 The preview or the changed billing cycle.

{
"dryRun": true,
"changed": false,
"currentBillingCycle": "monthly",
"targetBillingCycle": "annually",
"targetAmount": 999,
"currencyCode": "SEK",
"wouldBlock": false
}
Response fields
dryRunboolean
Always true on a preview.
changedboolean
Always false on a preview.
currentBillingCyclestring
The billing cycle the VPS has now. One of monthly, quarterly, semiannually, annually, biennially, triennially, free.
targetBillingCyclestring
The cycle you asked for. One of monthly, quarterly, semiannually, annually, biennially, triennially, free.
targetAmountnumber
Price for one period of the new cycle.
currencyCodestring
ISO 4217 currency code.
wouldBlockboolean
true when an open invoice or order would stop the change. Send cancelExistingInvoice: true to go ahead anyway.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400Invalid request. The response body is an RFC 7807 Problem Details document.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is vps_not_found.
409The change is blocked. existing_invoice_blocking: an unpaid renewal invoice or an open order exists; pay it or resend with cancelExistingInvoice: true. existing_invoice_not_cancellable: the open invoice cannot be cancelled and replaced automatically; pay it first. overdue_invoice_blocking: the invoice also bills web hosting whose paid period has ended; pay it first. Both name the invoice in existingInvoice and carry recovery.action: "pay_outstanding_invoice". scheduled_change_in_progress: a scheduled change already manages this VPS.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.