Order a VPS
order_vpsOrder a VPS. product = plan slug from list_plans; os_id = an OS id from that plan's images. Optional hostname and ssh_key (public key — strongly recommended so you get key-based root login). Optional location: "de" (Germany) or "fi" (Finland) — omit it and we pick the location automatically. Orders are never refused for capacity: if the chosen country has no free room or IPv4 right now, the paid server waits in the creation queue in that same country (get_vps_status shows queued: true) and is created automatically, usually within 24 hours; the customer gets the usual access email. Optional months (1–36): the billing term paid upfront — the invoice is the monthly price × months, payment moves the paid-until date by exactly that many months, after that the server renews monthly from the balance; months: 12 is the annual plan with its discount; terms other than 1 and 12 have no discount. Or period ("month" by default, or "year" for annual billing) or an explicit plan_id from list_plans plans[] (months takes precedence over both); an active automatic offer (plans[].promo) is applied to the first invoice and the response then carries promo. Windows plans (windows-*) accept only the Windows Server 2022 image, ignore ssh_key, and are reached over RDP as Administrator (see get_vps_status → access); the licence is BYOL.
Branching on the response:
• paid_from_balance: true → the prepaid balance covered it; the server is provisioning. Poll get_vps_status until status is active and the VM is reachable.
• paid_from_balance: false → balance was insufficient; an unpaid invoice is returned. Call pay_invoice with invoice.id: it pays from the balance if the balance now covers it, otherwise it returns a crypto checkout_url. Or topup_balance and then pay_invoice (or re-order).
Several servers in one order: quantity 2–50 → one invoice, N separate services (each with its own renewal), names -1…-N, created one after another after payment (service_ids in the response). 50 is only a typo guard — there is no limit for new accounts and no maximum by free capacity: servers that do not fit right now are queued for creation (usually within 24 hours). Promo codes apply to single-server orders paid for 1 or 12 months only. Optional addons: "backups" (Managed Backups, monthly plans only — annual plans include them) and "extra_ipv4" (a second public IPv4, dedicated-IP plans only); each add-on is added to the same invoice for every month of the chosen term (the first month on an annual plan), see get_order_limits for availability and price. Send the same idempotency_key when you retry the same order — a repeated call returns the existing order instead of creating a second one. Requires: token + enough balance (else an unpaid invoice is returned). Never refused for capacity: no free room/IPv4 → the paid server is queued (get_vps_status queued: true, usually ready within 24 hours). Typical errors: 422 unknown product/os_id (see list_plans), 422 quantity above 50, 422 months outside 1–36, 422 coupon_term_only (promo code with a term other than 1 or 12 months).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| os_id | Yes | Required. OS image id from the chosen plan's `available_os` in list_plans, integer, e.g. 4 (Ubuntu 24.04). | |
| addons | No | Optional. Add-ons created automatically with each server: "backups", "extra_ipv4". | |
| months | No | Optional. Billing term in months, 1–36 (default 1). Invoice = monthly price × months; 12 = the annual plan with its discount; other terms have no discount. Takes precedence over period/plan_id. | |
| period | No | Optional. Billing period: "month" (default) or "year" (annual plan). Ignored when `months` or `plan_id` is given. | |
| plan_id | No | Optional. Explicit billing plan id from list_plans `plans[].plan_id`, integer, e.g. 12. Ignored when `months` is given. | |
| product | Yes | Required. Plan slug from list_plans, e.g. "nano-ip", "small" or "windows-medium-ip". | |
| ssh_key | No | Optional. OpenSSH public key for root login, one line, e.g. "ssh-ed25519 AAAAC3Nza… you@laptop". Strongly recommended for Linux; ignored on Windows plans. Default: none (a root password is generated). | |
| hostname | No | Optional. Server hostname, a valid DNS name up to 128 characters (letters, digits, dots, hyphens), e.g. "web-1". Default: generated. | |
| location | No | Optional. Server country: "de" (Germany) or "fi" (Finland). Omit for automatic placement. | |
| quantity | No | Optional. How many identical servers to order in one invoice (1–50, default 1). Servers without free room right now are queued for creation, not refused. | |
| idempotency_key | No | Optional. Retry key of 1–64 letters, digits, "-" or "_", e.g. "web1-2026-10-20". Send the same key when retrying the same order — the existing order is returned instead of creating a second one. Default: none. |