---
title: "Create order"
method: POST
path: "/preview/v2/orders"
tags: ["Orders"]
---

# Create order

`POST /preview/v2/orders`

> ⚠️ This endpoint is in [public preview](/preview/roadmap).

Place a buy or sell order. Orders fill completely or not at all. All nodes fill on a single instance SKU matching the order's `requirements`. Order filling is asynchronous; poll `GET /v2/orders/{id}` to check status.

## Headers

- `Idempotency-Key` string, nullable

## Request body

- SfcApiV2CreateOrderRequest
  - `capacity` string, required — A resource path like 'sfc:capacity:acme:prod:my-capacity' _or_ an ID. Resource paths are human-readable but not stable - they change when resources are renamed or moved. IDs are stable and permanent.
  - `side` 'sell' | 'buy', required
  - `allow_standing` boolean — If true, the order rests on the order book until it fills, is cancelled, or its end time passes. If false, the order is cancelled immediately if it does not fill.
  - `instance_sku` string, required
  - `allocation_schedule_delta` SfcApiScheduleEntry[], required — Node count over time, as a list of `[start_at, end_at)` time ranges. Example: 5 nodes from t=0 to t=3600 is `[{"start_at": 0, "end_at": 3600, "node_count": 5}]`. `start_at` and `end_at` must be 60-second aligned, `node_count` must be non-negative. On non-final entries, `end_at` may be omitted (inferred from the next entry's `start_at`); gaps fill with `node_count: 0`.
    - `start_at` integer, required — Unix timestamp.
    - `end_at` integer — Unix timestamp.
    - `node_count` integer, required
  - `limit_price_dollars_per_node_hour` string, required — Price rate in dollars per node-hour.

## Response `201`

Order created.

- SfcApiV2OrderResponse
  - `object` 'order', required
  - `id` string, required
  - `capacity` SfcApiCapacitySummary, required
    - `id` string, required
    - `name` string, required
  - `side` 'sell' | 'buy', required
  - `allow_standing` boolean, required — If true, the order stays in the order book until either fills, is explicitly cancelled, or the order end time is reached resulting in automatic cancellation. If false, the order is cancelled immediately if it doesn't fill.
  - `instance_sku` SfcApiInstanceSkuSummary — Summary view of an instance SKU embedded on responses that reference one (orders, procurements, instances, capacity transfers). Carries both the id and the human-readable name. Legacy SKUs whose `name` column hasn't been backfilled use `UNKNOWN_INSTANCE_SKU_NAME` as a placeholder so this field is always populated on the wire.
    - `id` string, required
    - `name` string, required
  - `allocation_schedule_delta` SfcApiScheduleEntry[], required — Node count over time, as a list of `[start_at, end_at)` time ranges. Example: 5 nodes from t=0 to t=3600 is `[{"start_at": 0, "end_at": 3600, "node_count": 5}]`. `start_at` and `end_at` must be 60-second aligned, `node_count` must be non-negative. On non-final entries, `end_at` may be omitted (inferred from the next entry's `start_at`); gaps fill with `node_count: 0`.
    - `start_at` integer, required — Unix timestamp.
    - `end_at` integer — Unix timestamp.
    - `node_count` integer, required
  - `limit_price_dollars_per_node_hour` string, required — Price rate in dollars per node-hour.
  - `status` 'pending' | 'filled' | 'rejected' | 'cancelled' | 'standing', required — The status of an order in the system. `pending` = not resolved/processed yet. `filled` = order executed. `standing` = the order is waiting for a match. `cancelled` = the order was cancelled either automatically (not a standing order and didn't immediately fill, or current time past `end_at`) or by explicit cancellation. `rejected` = validation/system error occurred.
  - `created_at` integer, required — Unix timestamp.
  - `filled_at` integer — Unix timestamp.
  - `filled_quantity` integer, nullable — Node count that filled. Equals the order's quantity for complete fills.
  - `filled_average_price_dollars_per_node_hour` string — Price rate in dollars per node-hour.
  - `fills` SfcApiV2OrderFill[] — Each contract produced by this order. Empty for unfilled orders.
    - `contract` string
    - `filled_at` integer, required — Unix timestamp.
    - `allocation_schedule_delta` SfcApiScheduleEntry[], required — Node count over time, as a list of `[start_at, end_at)` time ranges. Example: 5 nodes from t=0 to t=3600 is `[{"start_at": 0, "end_at": 3600, "node_count": 5}]`. `start_at` and `end_at` must be 60-second aligned, `node_count` must be non-negative. On non-final entries, `end_at` may be omitted (inferred from the next entry's `start_at`); gaps fill with `node_count: 0`.
      - `start_at` integer, required — Unix timestamp.
      - `end_at` integer — Unix timestamp.
      - `node_count` integer, required
    - `price_dollars_per_node_hour` string, required — Price rate in dollars per node-hour.
  - `cancelled_at` integer — Unix timestamp.

## Other responses

- `401` — Unauthorized.
- `402` — Insufficient balance.
- `403` — Forbidden.
- `404` — Not found.
- `422` — Validation failed.
- `500` — Internal server error.
- `503` — Service temporarily unavailable. Try again later.

---

[API](https://skmtc.net/sfcompute/apis/san-francisco-compute-documentation.md) · [All operations](https://skmtc.net/sfcompute/apis/san-francisco-compute-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sfcompute/san-francisco-compute-documentation/revisions/93dd7661e9bb/schema)