Orders

Place an order for an instant server, paid from your account credit, and follow your orders until the server is ready. Reading needs read; ordering needs order. For a step-by-step walk-through see the Ordering guide.

Place an order

POST /orders orders one instant server. It is paid from the account's credit at once; there is no card or invoice step. Needs an Idempotency-Key (except for a dry run).

Any other field, a field of the wrong type, or a name given twice is 400 invalid_body. The configuration is always the offer's default one with your chosen OS. Quantity is one server per order.

Dry run

Add ?dry_run=true to see the exact total and check the order would go through. Nothing is ordered, reserved or charged. No Idempotency-Key is needed, and expected_total may be left out.

curl -sS -X POST "https://api.redswitches.com/v1/orders?dry_run=true" \
  -H "Authorization: Bearer $REDSWITCHES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offer_id":"ofr_12","billing_cycle":"monthly","os_id":"os_31","ssh_key_id":"sshkey_7"}'

const quote = await rs.orders.create(
  { offer_id: "ofr_12", billing_cycle: "monthly", os_id: "os_31", ssh_key_id: "sshkey_7" },
  { dryRun: true },
);

quote = client.orders.create(
    offer_id="ofr_12", billing_cycle="monthly", os_id="os_31", ssh_key_id="sshkey_7", dry_run=True
)

quote, err := client.Orders.Create(ctx, &redswitches.OrderCreateRequest{
	OfferID: "ofr_12", BillingCycle: "monthly", OSID: "os_31", SSHKeyID: "sshkey_7",
}, &redswitches.OrderOptions{DryRun: true})

{
  "dry_run": true,
  "offer_id": "ofr_12",
  "billing_cycle": "monthly",
  "total": { "amount": "15480", "currency": "USD" },
  "recurring": { "amount": "12900", "currency": "USD" },
  "paid_from_credit": { "amount": "15480", "currency": "USD" }
}

The answer is 200. total is the first payment including setup and tax; recurring is the monthly renewal amount before tax. Both are minor units. A dry run runs the same checks as a real order (stock, limits, credit), so it fails with the same errors.

Order

Send the same body with expected_total set to the dry run's total:

curl -sS -X POST https://api.redswitches.com/v1/orders \
  -H "Authorization: Bearer $REDSWITCHES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-web-1-2026-11-15" \
  -d '{"offer_id":"ofr_12","billing_cycle":"monthly","os_id":"os_31","ssh_key_id":"sshkey_7","label":"web-1","expected_total":{"amount":"15480","currency":"USD"}}'

const order = await rs.orders.create(
  {
    offer_id: "ofr_12",
    billing_cycle: "monthly",
    os_id: "os_31",
    ssh_key_id: "sshkey_7",
    label: "web-1",
    expected_total: quote.total,
  },
  { idempotencyKey: "order-web-1-2026-11-15" },
);

order = client.orders.create(
    offer_id="ofr_12",
    billing_cycle="monthly",
    os_id="os_31",
    ssh_key_id="sshkey_7",
    label="web-1",
    expected_total=quote.total,
    idempotency_key="order-web-1-2026-11-15",
)

order, err := client.Orders.Create(ctx, &redswitches.OrderCreateRequest{
	OfferID: "ofr_12", BillingCycle: "monthly", OSID: "os_31", SSHKeyID: "sshkey_7", Label: "web-1",
	ExpectedTotal: quote.Total,
}, &redswitches.OrderOptions{IdempotencyKey: "order-web-1-2026-11-15"})

{
  "id": "ord_456",
  "invoice_id": "inv_789",
  "server_ids": ["srv_123"],
  "status": "paid",
  "delivery": "queued",
  "billing_cycle": "monthly",
  "total": { "amount": "15480", "currency": "USD" },
  "recurring": { "amount": "12900", "currency": "USD" },
  "paid_from_credit": { "amount": "15480", "currency": "USD" },
  "poll_after": 30
}

The answer is 201 Created: the order exists and is paid. Delivery starts on its own. Follow it with GET /orders/{id}.

The root password never appears in the API. The welcome email with the login details goes to the account owner, as for any order.

Order errors

If an order times out, send exactly the same request again with the same Idempotency-Key. You get the original result; you never get a second server. See Idempotency and retries.

List orders

GET /orders returns the account's orders, newest first. Paged with limit (1 to 100, default 50) and cursor (ord_…).

curl -sS "https://api.redswitches.com/v1/orders?limit=20" \
  -H "Authorization: Bearer $REDSWITCHES_API_KEY"

const page = await rs.orders.list({ limit: 20 });

page = client.orders.list(limit=20)

page, err := client.Orders.List(ctx, &redswitches.ListOptions{Limit: 20})

{
  "data": [
    {
      "id": "ord_456",
      "date": "2026-11-15T09:30:00Z",
      "status": "active",
      "payment": "paid",
      "invoice": "inv_789",
      "services": [{ "id": "srv_123", "delivery": "installing" }],
      "poll_after": 30
    }
  ],
  "next_cursor": null
}

Get an order

GET /orders/{id} returns one order. Poll it after ordering until every service's delivery is ready.

curl -sS https://api.redswitches.com/v1/orders/ord_456 \
  -H "Authorization: Bearer $REDSWITCHES_API_KEY"

const ready = await rs.orders.waitUntilReady("ord_456");

ready = client.orders.wait_until_ready("ord_456")

order, err := client.Orders.Get(ctx, "ord_456")

{
  "id": "ord_456",
  "date": "2026-11-15T09:30:00Z",
  "status": "active",
  "payment": "paid",
  "invoice": "inv_789",
  "services": [{ "id": "srv_123", "delivery": "ready" }],
  "poll_after": null
}

Delivery states: