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

# Orders

> Place, update, cancel, and preview orders with the Python SDK

## Overview

The Orders API allows you to execute trades, modify existing orders, cancel orders, and preview orders before execution. All order operations require proper authentication and trading permissions.

## Class Reference

```python theme={null}
from aries_exchange import AriesClient

client = AriesClient(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

# Access orders methods
orders = client.orders
```

## Methods

### place\_order()

Place a new trading order.

```python theme={null}
order = client.orders.place_order(
    symbol="AAPL",
    quantity=10,
    side="buy",
    order_type="market",
    time_in_force="day"
)
print(f"Order ID: {order.id}")
print(f"Status: {order.status}")
```

**Parameters:**

* `symbol` (str): Stock symbol (e.g., "AAPL", "TSLA")
* `quantity` (int): Number of shares
* `side` (str): "buy" or "sell"
* `order_type` (str): "market", "limit", "stop", or "stop\_limit"
* `price` (float, optional): Limit price for limit orders
* `stop_price` (float, optional): Stop price for stop orders
* `time_in_force` (str): "day", "gtc", "ioc", "fok"

**Returns:** Order object

### update\_order()

Modify an existing order.

```python theme={null}
updated_order = client.orders.update_order(
    order_id="ord_123456",
    quantity=15,
    price=150.50
)
```

**Parameters:**

* `order_id` (str): Order ID to update
* `quantity` (int, optional): New quantity
* `price` (float, optional): New limit price

**Returns:** Updated order object

### cancel\_order()

Cancel an active order.

```python theme={null}
result = client.orders.cancel_order(order_id="ord_123456")
print(f"Cancellation status: {result.status}")
```

**Parameters:**

* `order_id` (str): Order ID to cancel

**Returns:** Cancellation result object

### preview\_order()

Preview order cost and impact before placing.

```python theme={null}
preview = client.orders.preview_order(
    symbol="AAPL",
    quantity=100,
    side="buy",
    order_type="market"
)
print(f"Estimated cost: ${preview.estimated_cost}")
print(f"Commission: ${preview.commission}")
print(f"Total: ${preview.total}")
```

**Parameters:** Same as `place_order()`

**Returns:** Order preview object with cost estimates

## Order Types

### Market Orders

Buy or sell immediately at the best available price:

```python theme={null}
# Market buy order
market_buy = client.orders.place_order(
    symbol="AAPL",
    quantity=10,
    side="buy",
    order_type="market"
)

# Market sell order
market_sell = client.orders.place_order(
    symbol="AAPL",
    quantity=10,
    side="sell",
    order_type="market"
)
```

### Limit Orders

Buy or sell at a specified price or better:

```python theme={null}
# Limit buy order - buy at $150 or lower
limit_buy = client.orders.place_order(
    symbol="AAPL",
    quantity=10,
    side="buy",
    order_type="limit",
    price=150.00
)

# Limit sell order - sell at $160 or higher
limit_sell = client.orders.place_order(
    symbol="AAPL",
    quantity=10,
    side="sell",
    order_type="limit",
    price=160.00
)
```

### Stop Orders

Trigger a market order when price reaches stop price:

```python theme={null}
# Stop loss - sell if price drops to $145
stop_loss = client.orders.place_order(
    symbol="AAPL",
    quantity=10,
    side="sell",
    order_type="stop",
    stop_price=145.00
)

# Buy stop - buy if price rises to $155
buy_stop = client.orders.place_order(
    symbol="AAPL",
    quantity=10,
    side="buy",
    order_type="stop",
    stop_price=155.00
)
```

### Stop-Limit Orders

Trigger a limit order when stop price is reached:

```python theme={null}
# Stop-limit sell - if price drops to $145, sell at $144.50 or better
stop_limit = client.orders.place_order(
    symbol="AAPL",
    quantity=10,
    side="sell",
    order_type="stop_limit",
    stop_price=145.00,
    price=144.50
)
```

## Time in Force

### Day Orders (DAY)

Order is active only for the current trading day:

```python theme={null}
day_order = client.orders.place_order(
    symbol="AAPL",
    quantity=10,
    side="buy",
    order_type="limit",
    price=150.00,
    time_in_force="day"
)
```

### Good 'Til Cancelled (GTC)

Order remains active until filled or cancelled:

```python theme={null}
gtc_order = client.orders.place_order(
    symbol="AAPL",
    quantity=10,
    side="buy",
    order_type="limit",
    price=150.00,
    time_in_force="gtc"
)
```

### Immediate or Cancel (IOC)

Fill immediately, cancel any unfilled portion:

```python theme={null}
ioc_order = client.orders.place_order(
    symbol="AAPL",
    quantity=10,
    side="buy",
    order_type="limit",
    price=150.00,
    time_in_force="ioc"
)
```

### Fill or Kill (FOK)

Fill entire order immediately or cancel:

```python theme={null}
fok_order = client.orders.place_order(
    symbol="AAPL",
    quantity=10,
    side="buy",
    order_type="limit",
    price=150.00,
    time_in_force="fok"
)
```

## Multi-Leg Orders

For complex options strategies:

```python theme={null}
multi_leg_order = client.orders.place_order(
    symbol="AAPL",
    legs=[
        {
            "symbol": "AAPL250117C00150000",  # Call option
            "quantity": 1,
            "side": "buy",
            "option_type": "call"
        },
        {
            "symbol": "AAPL250117P00140000",  # Put option
            "quantity": 1,
            "side": "sell",
            "option_type": "put"
        }
    ],
    order_type="market"
)
```

## Examples

### Preview Before Trading

Always preview orders to check costs:

```python theme={null}
# Preview the order
preview = client.orders.preview_order(
    symbol="TSLA",
    quantity=5,
    side="buy",
    order_type="market"
)

print("Order Preview:")
print(f"Estimated price: ${preview.estimated_price}")
print(f"Estimated cost: ${preview.estimated_cost}")
print(f"Commission: ${preview.commission}")
print(f"Total: ${preview.total}")

# If acceptable, place the order
if preview.total <= 5000:
    order = client.orders.place_order(
        symbol="TSLA",
        quantity=5,
        side="buy",
        order_type="market"
    )
    print(f"Order placed: {order.id}")
else:
    print("Order exceeds budget")
```

### Bracket Order Strategy

Place entry with automatic profit target and stop loss:

```python theme={null}
# Entry order
entry = client.orders.place_order(
    symbol="NVDA",
    quantity=10,
    side="buy",
    order_type="limit",
    price=500.00
)

print(f"Entry order: {entry.id}")

# Wait for fill or check status
if entry.status == "filled":
    entry_price = entry.average_fill_price

    # Profit target - 5% gain
    profit_target = client.orders.place_order(
        symbol="NVDA",
        quantity=10,
        side="sell",
        order_type="limit",
        price=entry_price * 1.05,
        time_in_force="gtc"
    )

    # Stop loss - 3% loss
    stop_loss = client.orders.place_order(
        symbol="NVDA",
        quantity=10,
        side="sell",
        order_type="stop",
        stop_price=entry_price * 0.97,
        time_in_force="gtc"
    )

    print(f"Profit target: {profit_target.id}")
    print(f"Stop loss: {stop_loss.id}")
```

### Modify Order

Update quantity or price of pending order:

```python theme={null}
# Place initial order
order = client.orders.place_order(
    symbol="AAPL",
    quantity=10,
    side="buy",
    order_type="limit",
    price=150.00
)

# Market moved, update the price
updated_order = client.orders.update_order(
    order_id=order.id,
    price=151.00,  # New limit price
    quantity=15    # Increase quantity
)

print(f"Order updated: {updated_order.id}")
print(f"New price: ${updated_order.price}")
print(f"New quantity: {updated_order.quantity}")
```

### Cancel Orders

```python theme={null}
# Cancel a specific order
result = client.orders.cancel_order(order_id="ord_123456")

# Cancel multiple orders
order_ids = ["ord_123456", "ord_789012", "ord_345678"]
for order_id in order_ids:
    try:
        result = client.orders.cancel_order(order_id=order_id)
        print(f"Cancelled: {order_id}")
    except Exception as e:
        print(f"Failed to cancel {order_id}: {e}")
```

## Error Handling

```python theme={null}
from aries_exchange import AriesAPIError

try:
    order = client.orders.place_order(
        symbol="AAPL",
        quantity=10,
        side="buy",
        order_type="market"
    )
except AriesAPIError as e:
    if e.code == "insufficient_funds":
        print("Not enough buying power")
    elif e.code == "invalid_symbol":
        print("Invalid stock symbol")
    elif e.code == "market_closed":
        print("Market is closed")
    elif e.code == "order_rejected":
        print(f"Order rejected: {e.message}")
    else:
        print(f"Error: {e.message}")
```

## Response Objects

### Order Object

```python theme={null}
{
    "id": "ord_123456",
    "symbol": "AAPL",
    "quantity": 10,
    "side": "buy",
    "order_type": "limit",
    "price": 150.00,
    "status": "pending",  # pending, filled, partially_filled, cancelled, rejected
    "filled_quantity": 0,
    "average_fill_price": 0.0,
    "time_in_force": "day",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
}
```

### Preview Object

```python theme={null}
{
    "symbol": "AAPL",
    "quantity": 10,
    "estimated_price": 150.50,
    "estimated_cost": 1505.00,
    "commission": 0.00,
    "fees": 0.50,
    "total": 1505.50,
    "buying_power_effect": -1505.50
}
```

## Best Practices

1. **Always preview orders** before placing to check costs
2. **Use limit orders** in volatile markets to control execution price
3. **Set stop losses** to manage risk on positions
4. **Use appropriate time\_in\_force** based on your strategy
5. **Handle errors gracefully** with proper error handling
6. **Check order status** after placement to confirm execution
7. **Cancel stale orders** to avoid unintended fills

## Related APIs

* [Accounts](/sdks/python/accounts) - Check account balances and positions before trading
* [Market Data](/sdks/python/market-data) - Get current prices for order placement
* [Users](/sdks/python/users) - Retrieve trading accounts

## API Endpoints

This SDK wraps the following REST API endpoints:

* `POST /v1/orders` - Place order
* `PUT /v1/orders` - Update order
* `DELETE /v1/orders` - Cancel order
* `POST /v1/orders/preview` - Preview order