> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sfcompute.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orders

> Buy and sell compute time

Orders are how you acquire and release compute time. A buy order increases your
[pool's](https://docs.sfcompute.com/preview/pools.md) allocation schedule. A sell order decreases it and returns credits to your
balance.

## Buy orders

Place a buy order to get compute time on a pool. `--max-rate` is the most you'll pay in dollars per
node-hour; 1 node is 8 GPUs. You can also use `--max-price` to set a maximum total for the order
instead.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h --max-rate 20.00
```

If the orderbook has availability at your rate, the order fills immediately. Otherwise, SF Compute
cancels the order by default (immediate-or-cancel).

To keep the order on the orderbook until it fills or you cancel it, use `--allow-standing`.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h \
  --max-rate 20.00 --allow-standing
```

A buy order fills completely or not at all by default. Pass `--allow-partial` to let it fill part of
the requested nodes or time window instead, which leaves the order `partially_filled`. A sell order
allows partial fills by default, since a seller usually wants any buyer for any part of the offered
supply. Pass `--allow-partial=false` to require an all-or-nothing fill on a sell.

### Guaranteed and callable reservations

SF Compute has two types of reservations, or buy orders: guaranteed and callable. The console
labels them **Guaranteed** and **Callable**.

A guaranteed reservation is a standard buy order. The compute time it buys is yours for the full
duration unless you sell it. It counts toward your [compute limit](https://docs.sfcompute.com/preview/limits.md#compute-limits).

A callable reservation lists the compute time it buys for sale at a multiple of your max rate. If
another customer calls that time by buying a listing, you give up that time and get paid for it. In
exchange, the order doesn't count toward your compute limit. See
[Callable buy orders](#callable-buy-orders).

In the CLI, a buy order is guaranteed unless you set `--preemption-multiple`.

## Pin to a SKU

You pin every order to a single SKU; the order fills only on that SKU. Pass
`--sku <id>` to pick one directly.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h \
  --max-rate 20.00 \
  --sku sku_4UpxzQw7A8N
```

Running `sf orders create` without `--sku` opens an interactive picker that shows every
registered SKU's name, ID, and properties. In non-interactive mode (`--no-input`), `--sku`
is required. Run `sf skus list` to browse them beforehand. See
[SKUs](https://docs.sfcompute.com/preview/instance-skus.md) for the full model.

## Sell orders

Sell back compute time you own.

```bash theme={null}
sf orders create --side sell --pool dev --count 1 \
  --start now --duration 1h --min-rate 8.00 --allow-standing
```

When a sell order fills, you receive credits and your pool's allocation decreases. Instances on that
pool that no longer have allocated time will terminate.

A sell order fills only from the first
[allocation schedule grid](https://docs.sfcompute.com/api-reference/platform/get-platform-constants.md#response-allocation-schedule-grid)
time at least 5 minutes away, so you get at least 5 minutes of notice before your instances
terminate.

> [!NOTE]
>
> Sell orders are not guaranteed to fill. Use `--allow-standing` to keep the order on the orderbook
> until a buyer matches.

## Sell fees

When a sell order executes, SF Compute deducts a variable
[platform fee](https://docs.sfcompute.com/preview/guides/reselling.md#platform-fee) from the fill price. You receive the fill
price minus the fee as credits. The CLI shows the estimated fee before you confirm an order.

Buy orders have no fees.

## Callable buy orders

> [!WARNING]
>
> Callable buy orders are in [public preview](https://docs.sfcompute.com/preview/roadmap.md#feature-states).

A callable reservation lets you reserve compute beyond your
[compute limit](https://docs.sfcompute.com/preview/limits.md#compute-limits). In return, other customers can call that time from
you at a resale price you set. If someone does, your instances on that time stop and you receive
credits for it. To make a buy order callable, set `_preview_preemption_limit_price_multiple` in the
API or `--preemption-multiple` in the CLI.

Use callable reservations for inference and training workloads that can restart if their instances
stop.

### How resale pricing works

When you buy, you set a resale price: your max rate times a multiple above 1.0, up to 1.5. Once
your order fills, SF Compute lists your compute for sale at that price, and anyone can buy some or
all of it.

For example, you buy at $20/node-hour with a 1.25 multiple. SF Compute lists your compute at
$25/node-hour. If someone calls an hour of it, you give up that hour and receive $25 minus the [platform fee](https://docs.sfcompute.com/preview/guides/reselling.md#platform-fee), for time that cost you $20 or less.

### When someone calls your time

When another customer calls your time by buying your listing, SF Compute stops your instances on it
and pays you:

* Each affected instance receives an `instance.termination_imminent` [event](https://docs.sfcompute.com/preview/events.md) up to
  1 minute before it stops.
* Your instances on that time stop, lowest [priority](https://docs.sfcompute.com/preview/instances.md#instance-priority) first.
  Anything on the instance's disk is lost, so save checkpoints to
  [object storage](https://docs.sfcompute.com/preview/object-storage.md#save-and-resume-training-checkpoints).
* Only the nodes and hours they bought are affected. You keep the rest.
* You receive the sale price minus the platform fee as credits when the sale fills.

### Buy a callable reservation in the console

Choose **Callable** under **Reservation type**, then pick your resale price.

### Buy a callable order with the CLI

Add `--preemption-multiple` to your order. This order buys 1 node for 1 hour at up to
$20/node-hour and lists it at $25/node-hour.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h \
  --max-rate 20.00 --preemption-multiple 1.25
```

`sf pools extend` takes the same flag. If an interactive buy would take you over your compute limit,
the CLI offers to make it callable.

See your listings with `sf orders list --side sell`.

### Cancel listings and known gaps

Cancelling your order doesn't take your compute off the market. Cancel the listings themselves with
`sf orders cancel`. You can't cancel a listing if that would put you over your compute limit.

You can't yet pay more to keep your compute or change your resale price after buying.

## What you need to place an order

SF Compute doesn't set anything aside for an open order. It checks that you can cover the order when
you place it and again when it matches. Open orders don't reduce your balance.

* **Buy orders.** Your balance plus your credit line must cover every open buy order at its limit
  price, across its remaining window and node count. If it doesn't, placement fails with an
  insufficient-balance error. Add credits or cancel other buy orders, then try again.
* **Sell orders.** The pool must hold the compute you offer, beyond what its other open sell orders
  on that SKU already offer. If it doesn't, placement fails with a validation error. Cancel or
  reduce those orders, or sell from a pool that holds the compute.

If you spend credits or move compute and can no longer cover your open orders, SF Compute keeps your
oldest orders that still fit and cancels the rest. An order you can't cover when it matches doesn't
fill.

You pay the fill price when an order fills.

## Order statuses

| Status | Description |
| - | - |
| pending | Received and waiting to be matched |
| filled | Fully executed |
| partially\_filled | Partially executed; the unfilled remainder stays on the orderbook |
| standing | Waiting for a match on the orderbook |
| cancelled | No match found (immediate-or-cancel), manually cancelled, the order's window fully elapsed, you can no longer cover it, or your account can no longer trade |
| rejected | You couldn't cover it when it came to match, or a system error occurred |

A standing order (buy or sell) rests until it fills, you cancel it, or its window fully elapses. As
the current time passes the order's start, it keeps matching only over the un-elapsed remainder of
its window. It matches at its original per-node-hour limit price. The order's total value shrinks as
time elapses.

Once the whole window has elapsed the order stops matching and moves to `cancelled`; there is no
separate expiry or time-to-live field. This lapse timing is current behavior, not a guarantee.

## Check an order

Look up a single order by ID.

```bash theme={null}
sf orders get ordr_JLBu4arl9nSLMfF2Ole
```

```text theme={null}
| ORDER ID                ordr_JLBu4arl9nSLMfF2Ole
| SIDE                    buy
| STATUS                  filled at Mar 19, 4:48pm
| FILLED                  100%
| POOL                    dev (pool_nuO4nVSM8O3NnsRE7udBe)
| SKU                     sku_4UpxzQw7A8N
| RATE (PER 8X GPU NODE)  $20.00/node/hr (Limit)
|
| SCHEDULE                Mar 19, 5:00pm → Mar 19, 6:00pm: 1 node
```

## List orders

List orders in the active workspace.

```bash theme={null}
sf orders list
```

To list orders across your organization, use `--all`.

```bash theme={null}
sf orders list --all
```

```text theme={null}
-----------------------------------------------------------------------------------------------------------
SIDE  STATUS     PERIOD  NODES  RATE ($/NODE/HR, 8x GPU)  POOL  SKU              ID
sell  filled     Mar 19  1      ≥$8.00/node/hr            dev   sku_4UpxzQw7A8N  ordr_hYuOEmXWt3RqPd8KvA2Nc
buy   filled     Mar 19  1      ≤$20.00/node/hr           dev   sku_4UpxzQw7A8N  ordr_JLBu4arl9nSLMfF2Ole
buy   cancelled  Mar 12  1      ≤$20.00/node/hr           dev   sku_4UpxzQw7A8N  ordr_Qj69x65vLw4TmBn7RdEyS
```

Filter by side or status.

```bash theme={null}
sf orders list --side buy --status filled
```

Filter by time range.

```bash theme={null}
# Orders from the last 7 days
sf orders list --created-after 7d

# Orders within a specific window
sf orders list --created-after 2025-03-01 --created-before 2025-03-08

# Orders from a specific calendar month
sf orders list --month 2025-05
```

`--created-after` and `--created-before` accept a datetime, Unix timestamp, or a duration like `24h`
or `7d`. A duration means that long ago (24 hours or 7 days, respectively). You can also use
`--since` and `--until` as aliases.

## Cancel an order

Cancel an order that hasn't fully filled yet.

```bash theme={null}
sf orders cancel <order-id>
```

The order is cancelled when the request returns (`204 No Content` on the API). If the order is in
the middle of a fill, the request returns `503`. Try again in a few seconds.

Cancellation removes only the unfilled remainder from the orderbook and keeps the fills that
executed before it. Once the order is `cancelled`, its `fills` and
`filled_allocation_schedule_delta` are final and remain readable on the order in both get and list
responses.

## Start and end times

Order start and end times must be on the
[allocation schedule grid](https://docs.sfcompute.com/api-reference/platform/get-platform-constants.md#response-allocation-schedule-grid).
An order can also start at the current time.

## Allocation schedule deltas

`allocation_schedule_delta` describes how many nodes an order requests or offers during one or
more time intervals.

![An allocation\_schedule\_delta JSON entry mapped to eight nodes over a time interval. start\_at supplies the time for vertices A and B, end\_at supplies the time for C and D, and node\_count supplies the value for B and C.](https://mintcdn.com/sfcompute/FOad7tCEiZswvZiC/preview/images/orderbook-allocation-schedule.svg?fit=max\&auto=format\&n=FOad7tCEiZswvZiC\&q=85\&s=42d3e00c492dc61e4dd708772748e119)

Each object in the array is one schedule segment. `start_at` and `end_at` set the segment's time
bounds, while `node_count` specifies how many nodes apply during that interval. Multiple entries
can describe different node counts over adjacent intervals.

Schedule entries describe half-open intervals `[start_at, end_at)`: the node count applies at
`start_at`, but not at `end_at`. Adjacent entries therefore meet without overlapping. All segments
on an order refer to that order's single `instance_sku`.

In responses, a non-empty array always ends with a terminator entry whose `end_at` is `null` and
`node_count` is `0`, marking the schedule as open-ended and empty after the last segment. A schedule
with no capacity is returned as an empty array. Requests carry only the closed `[start_at, end_at)`
segments you submit and omit this terminator.

Orders are submitted with one node count over one delivery window, so
`allocation_schedule_delta` normally contains one segment. `filled_allocation_schedule_delta`
describes the portion that has executed so far and may contain multiple segments when different
parts of the order fill over different intervals. Subtract the filled node count from the
requested or offered node count at each instant to get the capacity that remains on the book.

For a buy, every filled segment adds to the destination pool's allocation schedule; for a sell, it
removes that segment. An orderbook fill reports the exact schedule segment that traded. To
calculate the compute represented by a schedule, sum `node_count × duration_hours` across its
entries.

## API examples

These worked examples use the `/v2` order endpoints; see the
[Orders API reference](https://docs.sfcompute.com/api-reference/orders/list-orders.md) for the full request and response
schemas. Timestamps are Unix epoch seconds, and prices are strings in dollars per node-hour.

Create a buy order with `POST /v2/orders`. The request body includes the following fields.

* `side` is `buy` or `sell`.
* `pool` accepts a pool ID or resource path.
* `sku` takes a SKU ID.
* `allocation_schedule_delta` is a single time range.

```json theme={null}
{
  "pool": "pool_2m9Xk4Qw7A8N",
  "side": "buy",
  "allow_standing": true,
  "allow_partial": false,
  "sku": "sku_4UpxzQw7A8N",
  "allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 }
  ],
  "limit_price_dollars_per_node_hour": "18.000000"
}
```

The response returns the order in `pending` state; poll `GET /v2/orders/{id}` for the resolved
state. The trailing zero entry marks the end of the schedule.

If SF Compute is behind on matching orders, the request returns `503`. Retry with the same
`Idempotency-Key` to avoid placing the order twice.

```json theme={null}
{
  "object": "order",
  "id": "ordr_JLBu4arl9nSLMfF2Ole",
  "pool": { "object": "pool_summary", "id": "pool_2m9Xk4Qw7A8N", "name": "dev" },
  "workspace": { "object": "workspace_summary", "id": "wksp_7Ct3nR2xL9", "name": "acme" },
  "side": "buy",
  "allow_standing": true,
  "allow_partial": false,
  "sku": { "object": "sku", "id": "sku_4UpxzQw7A8N", "alias": "h100i" },
  "allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
    { "start_at": 1742407200, "end_at": null, "node_count": 0 }
  ],
  "filled_allocation_schedule_delta": [],
  "limit_price_dollars_per_node_hour": "18.000000",
  "state": "pending",
  "created_at": 1742402883
}
```

A sell order takes the same body with `side` set to `sell`, and its response has the same shape.

```json theme={null}
{
  "pool": "pool_2m9Xk4Qw7A8N",
  "side": "sell",
  "allow_standing": true,
  "allow_partial": true,
  "sku": "sku_4UpxzQw7A8N",
  "allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 }
  ],
  "limit_price_dollars_per_node_hour": "9.000000"
}
```

Fetch one order with `GET /v2/orders/{id}`. Once filled, `state` is `filled`, `filled_at` is set,
and `filled_allocation_schedule_delta` covers the filled portion. `fills` lists each execution with
the price actually paid (here below the buy's limit).

```json theme={null}
{
  "object": "order",
  "id": "ordr_JLBu4arl9nSLMfF2Ole",
  "pool": { "object": "pool_summary", "id": "pool_2m9Xk4Qw7A8N", "name": "dev" },
  "workspace": { "object": "workspace_summary", "id": "wksp_7Ct3nR2xL9", "name": "acme" },
  "side": "buy",
  "allow_standing": true,
  "allow_partial": false,
  "sku": { "object": "sku", "id": "sku_4UpxzQw7A8N", "alias": "h100i" },
  "allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
    { "start_at": 1742407200, "end_at": null, "node_count": 0 }
  ],
  "filled_allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
    { "start_at": 1742407200, "end_at": null, "node_count": 0 }
  ],
  "limit_price_dollars_per_node_hour": "18.000000",
  "state": "filled",
  "created_at": 1742402883,
  "filled_at": 1742402889,
  "fills": [
    {
      "filled_at": 1742402889,
      "allocation_schedule_delta": [
        { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
        { "start_at": 1742407200, "end_at": null, "node_count": 0 }
      ],
      "price_dollars_per_node_hour": "15.000000"
    }
  ]
}
```

List orders with `GET /v2/orders`. Each entry in `data` is a full order object; pass the returned
`cursor` as `starting_after` to page forward.

```json theme={null}
{
  "object": "list",
  "has_more": false,
  "cursor": "ordrc_kQ8Vd2wwpU1s2Wey",
  "data": [
    {
      "object": "order",
      "id": "ordr_hYuOEmXWt3RqPd8KvA2Nc",
      "pool": { "object": "pool_summary", "id": "pool_2m9Xk4Qw7A8N", "name": "dev" },
      "workspace": { "object": "workspace_summary", "id": "wksp_7Ct3nR2xL9", "name": "acme" },
      "side": "sell",
      "allow_standing": true,
      "allow_partial": true,
      "sku": { "object": "sku", "id": "sku_4UpxzQw7A8N", "alias": "h100i" },
      "allocation_schedule_delta": [
        { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
        { "start_at": 1742407200, "end_at": null, "node_count": 0 }
      ],
      "filled_allocation_schedule_delta": [],
      "limit_price_dollars_per_node_hour": "9.000000",
      "state": "standing",
      "created_at": 1742402883
    }
  ]
}
```

Cancel with `POST /v2/orders/{id}/cancel`, which returns `204 No Content`.

```http theme={null}
POST /v2/orders/ordr_hYuOEmXWt3RqPd8KvA2Nc/cancel
```
