Change the plan of a VPS
POST /api/v2/vps/{id}/actions/upgrade
Changes the plan of a VPS. Send dryRun: true first to preview the change and its price without changing anything. Take productSlug from availablePlans[].slug on GET /api/v2/vps/{id}/actions/upgrade. To change add-ons such as bandwidthGb without changing plan, use POST /api/v2/vps/{id}/actions/config instead. An upgrade with something to pay creates an invoice and returns status: awaiting_payment. The plan changes once that invoice is paid. If no saved payment method can pay it, the call returns 409 payment_method_unavailable. An upgrade with nothing to pay returns status: applied. A downgrade is booked for the next period and returns status: scheduled. The current plan stays until scheduledChange.effectiveAt. The current period is not refunded. Paid bandwidth above the current plan’s allowance moves to the new plan unless you send preserveExtraBandwidth: false. Only one change can be booked at a time. Cancel it with DELETE /api/v2/vps/{id}/actions/upgrade before you choose another.
Authentication: An API key with the scope write:billing. About keys and scopes
Request
Path parameters
idstringrequiredvps_…).Body
productSlugstringrequiredavailablePlans[].slug on GET /api/v2/vps/{id}/actions/upgrade, for example vps-sm.billingCyclestringmonthly, quarterly, semiannually, annually, biennially, triennially.dryRunbooleancancelExistingInvoicebooleanexisting_invoice_blocking. Default false.preserveExtraBandwidthbooleanExample
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/upgrade" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "productSlug": "vps-sm", "billingCycle": "monthly", "dryRun": true }'curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/upgrade" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "productSlug": "vps-sm", "billingCycle": "monthly" }'curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/upgrade" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "productSlug": "vps-xs", "billingCycle": "monthly", "dryRun": true, "preserveExtraBandwidth": false }'curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/upgrade" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "productSlug": "vps-xs", "billingCycle": "monthly", "preserveExtraBandwidth": false }'Responses
200 The preview or the result of the change.
{ "dryRun": true, "status": "preview", "changeKind": "upgrade", "currentProduct": { "id": "vpsprod_01hxa3b4c5d6e7f8g9h0j1k2m3", "slug": "vps-xs", "name": "VPS XS" }, "newProduct": { "id": "vpsprod_01j0b3c4d5e6f7g8h9j0k1m2n3", "slug": "vps-sm", "name": "VPS SM" }, "paymentInvoice": { "amount": 70, "currencyCode": "SEK", "servicePeriodEndAt": "2026-08-11T00:00:00.000Z" }, "renewalInvoice": { "amount": 149, "currencyCode": "SEK" }, "actions": { "canCommit": { "allowed": true, "reason": null } }, "warnings": []}{ "status": "scheduled", "changeKind": "downgrade", "scheduled": true, "scheduledChange": { "status": "scheduled", "effectiveAt": "2026-08-11T00:00:00.000Z", "invoiceIssueAt": "2026-07-28T00:00:00.000Z", "target": { "productSlug": "vps-xs", "billing": { "amount": 39, "currencyCode": "SEK", "billingCycle": "monthly" } }, "actions": { "canCancel": { "allowed": true, "reason": null } } }, "currentProduct": { "id": "vpsprod_01j0b3c4d5e6f7g8h9j0k1m2n3", "slug": "vps-sm", "name": "VPS SM" }, "newProduct": { "id": "vpsprod_01hxa3b4c5d6e7f8g9h0j1k2m3", "slug": "vps-xs", "name": "VPS XS" }, "paymentInvoice": null, "renewalInvoice": null, "warnings": []}Response fields
dryRunbooleanstatusstringpreview.changeKindstringupgrade, downgrade.currentProductobjectidstring or nullslugstring or nullnamestring or nullnewProductobjectidstring or nullslugstring or nullnamestring or nullpaymentInvoicenullrenewalInvoicenullactionsobjectcanCommitobjectallowedbooleanreasonstring or nullallowed is true.scheduledbooleanscheduledChangeobjectstatusstringpreview, scheduled, awaiting_payment, paid, applying, applied, needs_attention, cancelling, cancelled.effectiveAtstring or nullinvoiceIssueAtstring or nulltargetobjectproductSlugstringresourcesobjectstorageGb can be larger than the new plan’s disk. The primary disk cannot be made smaller.billingobjectamountnumber or nullcurrencyCodestringbillingCyclestringmonthly, quarterly, semiannually, annually, biennially, triennially, free.actionsobjectcanCancelobjectallowedbooleanreasonstring or nullallowed is true.warningsarray of objectcodestringpackage_bandwidth_preserved, package_bandwidth_adjusted, package_storage_preserved or package_config_option_preserved.severitystringwarning.resourcestringbandwidth, storage, backups, snapshots, ipv4, ipv6, attachableStorage.reasonstringincludedobjectvaluenumberunit.unitstringGB, slots, addresses.currentobjectvaluenumberunit.unitstringGB, slots, addresses.usageobjectvaluenumberunit.unitstringGB, slots, addresses.adjustedobjectvaluenumberunit.unitstringGB, slots, addresses.extraobjectvaluenumberunit.unitstringGB, slots, addresses.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 names the missing resource: vps_not_found, plan_not_found, scheduled_change_not_found. |
| 409 | The change cannot be made now. Branch on code: existing_invoice_blocking (an unpaid invoice blocks it; recovery.suggestedBody is the retry with cancelExistingInvoice: true), payment_method_unavailable (no saved payment method can pay the invoice), same_product_plan (the VPS already has this plan), unsupported_plan_transition (this plan change is not possible), scheduled_change_in_progress (cancel the booked change first), billing_change_busy (another billing change is running; retry shortly), scheduled_change_processing_unavailable (booked changes are unavailable for now; retry later) and renewal_period_review_required (support must check the renewal periods first). |
| 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. |
| 502 | The billing currency or the next renewal price could not be confirmed. Retry shortly. |