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

# Order Management

> Create, list, read, cancel, and replace exchange orders.

Order routes automate trading activity for your Stabyl account. Order writes
require `X-Api-Key` and `Idempotency-Key`. Matching is asynchronous. Consume
exchange webhooks or private WebSocket topics for timely changes, and use order
reads for recovery, operator lookups, and periodic reconciliation.

## Before You Place an Order

Perform these checks in your own system before sending the request:

1. Fetch `GET /partner/exchange/markets` and confirm the pair is enabled.
2. Validate `side`, `order_type`, `quantity`, and `price` against the market rules.
3. Confirm available balance with `GET /partner/wallets/balances/overview`.
4. Generate and store an `Idempotency-Key` for this exact order intent.
5. Configure exchange webhooks or private WebSocket topics before submission.

## Create A Limit Order

Limit orders specify the maximum buy price or minimum sell price you are willing to accept.

```bash theme={null}
curl https://api-staging.stabyl.com/v1/partner/exchange/orders \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -H "Idempotency-Key: 0198b730-7cc2-79e4-b04e-5b5c41a50221" \
  -d '{
    "pair_id": "USD/NGN",
    "side": "buy",
    "order_type": "limit",
    "price": "1520.00",
    "quantity": "100.00"
  }'
```

## Create A Market Order

Market orders prioritize execution against available liquidity. Because the final price depends on available depth, read the current ticker or order book first and keep your own risk controls conservative.

```bash theme={null}
curl https://api-staging.stabyl.com/v1/partner/exchange/orders \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -H "Idempotency-Key: 0198b730-7cc2-79e4-b04e-5b5c41a50222" \
  -d '{
    "pair_id": "USD/NGN",
    "side": "sell",
    "order_type": "market",
    "quantity": "50.00"
  }'
```

## Create Response

The response confirms that Stabyl accepted the order request for processing. It does not mean the order is already filled.

```json theme={null}
{
  "status": "success",
  "data": {
    "order_id": "0198b731-2830-7f5d-a10d-7a5fda480491",
    "pair_id": "USD/NGN",
    "side": "buy",
    "order_type": "limit",
    "status": "pending",
    "quantity": "100.00",
    "price": "1520.00"
  }
}
```

Store the returned `order_id`. Use it for all later reads, cancels, replacements, and reconciliation.

## List Orders By Status

```bash theme={null}
curl "https://api-staging.stabyl.com/v1/partner/exchange/orders?status=accepted" \
  -H "X-Api-Key: $STABYL_API_KEY"
```

Use list filters for dashboards and background reconciliation. For a single order, prefer the detail endpoint.

## Get Order Detail

```bash theme={null}
curl https://api-staging.stabyl.com/v1/partner/exchange/orders/0198b731-2830-7f5d-a10d-7a5fda480491 \
  -H "X-Api-Key: $STABYL_API_KEY"
```

## Cancel Order

```bash theme={null}
curl https://api-staging.stabyl.com/v1/partner/exchange/orders/0198b731-2830-7f5d-a10d-7a5fda480491/cancel \
  -X POST \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -H "Idempotency-Key: 0198b730-7cc2-79e4-b04e-5b5c41a50223"
```

Cancel is best effort for open quantity. If part of the order has already executed, the filled portion remains final and only remaining quantity can be cancelled.

## Replace Order

```bash theme={null}
curl https://api-staging.stabyl.com/v1/partner/exchange/orders/0198b731-2830-7f5d-a10d-7a5fda480491/replace \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -H "Idempotency-Key: 0198b730-7cc2-79e4-b04e-5b5c41a50221" \
  -d '{
    "price": "1518.00",
    "quantity": "100.00"
  }'
```

Replace creates a new order intent for the remaining quantity according to the API response. Always read the returned order and do not assume the original order is still active.

## Status Handling

| Status             | Your action                                                   |
| ------------------ | ------------------------------------------------------------- |
| `pending`          | Wait for an event and include it in periodic reconciliation   |
| `accepted`         | Treat as live until a later event or reconciliation update    |
| `partially_filled` | Apply each fill event and show executed and remaining amounts |
| `filled`           | Treat as terminal and reconcile all fills                     |
| `cancelled`        | Treat as terminal and reconcile any partial fills             |
| `rejected`         | Treat as terminal and surface the public reason               |
| `expired`          | Treat as terminal when returned by REST reconciliation        |

## Retry Rules

| Situation                           | What to do                                                 |
| ----------------------------------- | ---------------------------------------------------------- |
| Request timed out before a response | Retry with the same `Idempotency-Key`                      |
| Response was `429`                  | Back off, then retry with the same `Idempotency-Key`       |
| Response was `409`                  | Read the existing order or correct the conflicting request |
| Order status is terminal            | Do not retry the same action as a new order                |

Common failures include invalid pair, insufficient available balance, stale order status, or idempotency conflicts.