Skip to content

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

idstringrequired
The VPS ID (vps_…).

Body

productSlugstringrequired
Plan slug from availablePlans[].slug on GET /api/v2/vps/{id}/actions/upgrade, for example vps-sm.
billingCyclestring
Billing cycle for the new plan. One of monthly, quarterly, semiannually, annually, biennially, triennially.
dryRunboolean
Preview the price and payment options without changing anything. Default false.
cancelExistingInvoiceboolean
Cancel the unpaid invoice that blocks the change. Send it only to retry after 409 existing_invoice_blocking. Default false.
preserveExtraBandwidthboolean
Keep paid bandwidth above the current plan’s allowance on top of the new plan. Default true. With false, that extra bandwidth is dropped and unused paid time is not credited back.

Example

POST /api/v2/vps/{id}/actions/upgrade
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
}'

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": []
}
Response fields
dryRunboolean
statusstring
One of preview.
changeKindstring
One of upgrade, downgrade.
currentProductobject
A short reference to the current or the requested VPS plan.
idstring or null
slugstring or null
namestring or null
newProductobject
A short reference to the current or the requested VPS plan.
idstring or null
slugstring or null
namestring or null
paymentInvoicenull
renewalInvoicenull
actionsobject
canCommitobject
allowedboolean
True when the action can be called now.
reasonstring or null
Why the action is blocked, ready to show. Null when allowed is true.
scheduledboolean
scheduledChangeobject
statusstring
One of preview, scheduled, awaiting_payment, paid, applying, applied, needs_attention, cancelling, cancelled.
effectiveAtstring or null
invoiceIssueAtstring or null
targetobject
productSlugstring
resourcesobject
The resources after the change, as checked by the server. For a VPS plan change storageGb can be larger than the new plan’s disk. The primary disk cannot be made smaller.
billingobject
amountnumber or null
currencyCodestring
billingCyclestring
One of monthly, quarterly, semiannually, annually, biennially, triennially, free.
actionsobject
canCancelobject
allowedboolean
True when the action can be called now.
reasonstring or null
Why the action is blocked, ready to show. Null when allowed is true.
warningsarray of object
Adjustments the server made to the plan change. Examples: storage kept, paid extra bandwidth kept, bandwidth raised to cover use in the current period.
codestring
What was adjusted, for example package_bandwidth_preserved, package_bandwidth_adjusted, package_storage_preserved or package_config_option_preserved.
severitystring
One of warning.
resourcestring
One of bandwidth, storage, backups, snapshots, ipv4, ipv6, attachableStorage.
reasonstring
The adjustment in plain words, safe to show the customer.
includedobject
valuenumber
The amount, in the unit named by unit.
unitstring
One of GB, slots, addresses.
currentobject
valuenumber
The amount, in the unit named by unit.
unitstring
One of GB, slots, addresses.
usageobject
valuenumber
The amount, in the unit named by unit.
unitstring
One of GB, slots, addresses.
adjustedobject
valuenumber
The amount, in the unit named by unit.
unitstring
One of GB, slots, addresses.
extraobject
valuenumber
The amount, in the unit named by unit.
unitstring
One of GB, slots, addresses.

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 names the missing resource: vps_not_found, plan_not_found, scheduled_change_not_found.
409The 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).
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.
502The billing currency or the next renewal price could not be confirmed. Retry shortly.