---
title: "Order a VPS — or several identical ones in one invoice (paid from balance)"
method: POST
path: "/orders"
---

# Order a VPS — or several identical ones in one invoice (paid from balance)

`POST /orders`

## Request

- Base URL: `https://api.eqvps.com/api/v1/eqvps`
- URL: `https://api.eqvps.com/api/v1/eqvps/orders`
- Auth: HTTP bearer

Provisions a VPS from the prepaid balance; if the balance is short, an unpaid invoice is returned (pay it with POST /invoices/{id}/pay). See GET /products for plan slugs and os_id values. quantity 2–50 creates one invoice and N separate services (each with its own renewal), created one after another after payment; check GET /orders/limits first. months 1–36 pays the term upfront: the invoice is the monthly price × months, payment moves the paid-until date by exactly that many months, then the server renews monthly from the balance; months 12 is the annual plan with its discount, other terms have no discount. Promo codes apply to single-server orders paid for 1 or 12 months only. An unpaid multi-server order reserves capacity for 24 hours, one per account.

## Request body

- object
  - `product` string, required: Plan slug from GET /products
  - `os_id` integer, required: An available_os[].id of that plan
  - `hostname` string
  - `ssh_key` string: Public key for root
  - `period` 'month' | 'year'
  - `plan_id` integer
  - `months` integer: Billing term paid upfront (1–36 months). Invoice = monthly price × months; 12 = the annual plan with its discount. Takes precedence over period/plan_id.
  - `location` 'de' | 'fi': Omit for automatic placement
  - `coupon_code` string: Single-server orders paid for 1 or 12 months only
  - `quantity` integer
  - `addons` string[]: backups: monthly plans (annual plans include them); extra_ipv4: dedicated-IP plans. Each add-on is billed for every month of the chosen term (the first month on an annual plan).
  - `idempotency_key` string: Repeat it on retries: the same order is returned instead of a new one

## Response `200`

Same idempotency_key — the existing order is returned (reused: true)

## Other responses

- `201`: Order created: paid_from_balance true (provisioning) or an unpaid invoice; multi-server orders also return service_ids and quantity
- `402`: Insufficient balance
- `409`: reason: order_in_progress (a request for the same plan is already being processed — retry in a few seconds). Nothing is charged on 409.
- `422`: Validation error (unknown product/os_id, addon_unavailable, coupon_single_only)

---

[API](https://skmtc.dev/eqvps/apis/eqvps-api.md) · [All operations](https://skmtc.dev/eqvps/apis/eqvps-api/llms.txt) · [OpenAPI document](https://skmtc.dev/eqvps/apis/eqvps-api/revisions/2cbc15a2b088?raw)