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
idstringrequiredvps_…).Body
billingCyclestringrequiredmonthly, quarterly, semiannually, annually, biennially, triennially.dryRunbooleanfalse.cancelExistingInvoicebooleanfalse.Example
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 }'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" }'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", "cancelExistingInvoice": true }'Responses
200 The preview or the changed billing cycle.
{ "dryRun": true, "changed": false, "currentBillingCycle": "monthly", "targetBillingCycle": "annually", "targetAmount": 999, "currencyCode": "SEK", "wouldBlock": false}{ "changed": true, "currentBillingCycle": "annually", "currencyCode": "SEK", "renewalInvoice": null, "cancelledInvoiceIds": [ "inv_01hxa3b4c5d6e7f8g9h0j1k2m3" ], "cancellationMethod": "invoice", "invoiceLookupPending": true}Response fields
dryRunbooleantrue on a preview.changedbooleanfalse on a preview.currentBillingCyclestringmonthly, quarterly, semiannually, annually, biennially, triennially, free.targetBillingCyclestringmonthly, quarterly, semiannually, annually, biennially, triennially, free.targetAmountnumbercurrencyCodestringwouldBlockbooleantrue 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.
| 400 | Invalid request. The response body is an RFC 7807 Problem Details document. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is vps_not_found. |
| 409 | The 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. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |