Orders & Trading¶

All order endpoints follow a preview-then-place workflow. Place methods are blocked by default (dry-run mode) — pass live_trading=True to FidelityClient or set FIDELITY_LIVE_TRADING=true to enable.

Cancel operations are never gated by dry-run.

Order Status¶

Summary (all orders)¶

status = client.order_status.get_order_status(["Z12345678"])
for order in status.orders:
    print(f"{order.id_detail.conf_num}: {order.status_detail.status_desc}")

Single Order Detail¶

New in v0.3

Query detailed status for a single order by ID.

detail = client.order_status.get_order_detail("Z12345678", order_id="24B0XY3Z")
if detail.order:
    o = detail.order
    print(f"Status: {o.status_detail.status_desc}")
    print(f"Cancelable: {o.status_detail.cancelable_ind}")
    print(f"Replaceable: {o.status_detail.replaceable_ind}")

Response (OrderDetailResponse):

Property	Type	Description
`orders`	list[OrderDetail]	List of matching orders (usually 1)
`order`	OrderDetail or None	Convenience: first order or None

Service: GET /api/v1/orders/{order_id}/detail?acct=

Cancel Order¶

Cancel with Preview¶

New in v0.3

Two-step cancel: preview first to see warnings, then place. The app always previews before canceling.

# Step 1: Preview — see warnings and estimated proceeds
preview = client.cancel_order.preview_cancel(
    conf_num="24B0XY3Z",
    acct_num="Z12345678",
    action_code="B",
)

# Check for warnings (e.g., partial fill in progress)
for detail in preview.cancel_preview_detail:
    if detail.has_warnings:
        print(f"Warning: {detail.order_confirm_msgs}")
    print(f"Estimated proceeds: ${detail.est_proceeds}")
    print(f"Remaining qty: {detail.remaining_qty}")

# Step 2: Place the cancel (only if preview looks good)
if preview.is_accepted:
    result = client.cancel_order.cancel_order(
        conf_num="24B0XY3Z",
        acct_num="Z12345678",
        action_code="B",
    )
    print(f"Canceled: {result.is_accepted}")

Preview response fields (CancelPreviewDetail):

Field	Type	Description
`resp_type_code`	str	`"A"` = accepted
`conf_num`	str	Order confirmation number
`acct_num`	str	Account number
`action_code`	str	Original action (B=Buy, S=Sell)
`orig_qty`	float	Original order quantity
`exec_qty`	float	Quantity already executed
`remaining_qty`	float	Quantity that would be canceled
`est_proceeds`	float	Estimated proceeds from cancel
`commission`	float	Commission estimate
`order_confirm_msgs`	list	Warning messages (if any)

Properties:

detail.is_accepted — True when respTypeCode == "A"
detail.has_warnings — True when warnings exist

Service: POST /api/v1/orders/{conf_num}/cancel/preview (preview) and POST /api/v1/orders/{conf_num}/cancel (place)

Conditional Orders¶

Standard Preview & Place¶

from fidelity_trader.models.conditional_order import ConditionalOrderRequest, ConditionalOrderLeg

order = ConditionalOrderRequest(
    cond_order_type_code="OTO",  # OTO, OCO, OTOCO
    legs=[
        ConditionalOrderLeg(symbol="AAPL", order_action_code="B", qty=10, ...),
        ConditionalOrderLeg(symbol="AAPL", order_action_code="S", qty=10, ...),
    ],
)

preview = client.conditional_orders.preview_order(order)
result = client.conditional_orders.place_order(order, preview.conf_nums)

Conditional Replace¶

New in v0.3

Modify an existing conditional order. Uses a different API path than standard conditional.

# Preview the replacement
preview = client.conditional_orders.preview_replace(modified_order)

# Place the replacement (requires live_trading=True)
result = client.conditional_orders.place_replace(modified_order, preview.conf_nums)

Different API Path

Standard conditional uses /orderentry/conditional/{preview,place}/v1. Conditional replace uses /retail-condition-replace/v1/accounts/orders/{preview,place}. The SDK handles this automatically — just call preview_replace() / place_replace().

Service: POST /api/v1/orders/conditional/replace/{preview,place}

Equity Orders¶

from fidelity_trader.models.equity_order import EquityOrderRequest

order = EquityOrderRequest(
    acctNum="Z12345678",
    symbol="AAPL",
    orderActionCode="B",       # B=Buy, S=Sell, SS=Sell Short, BC=Buy to Cover
    qty=10,
    priceTypeCode="L",         # L=Limit, M=Market, S=Stop, SL=Stop Limit
    limitPrice=150.00,
    tifCode="D",               # D=Day, G=GTC
)

preview = client.equity_orders.preview_order(order)
result = client.equity_orders.place_order(order, preview.conf_num)

Service: POST /api/v1/orders/equity/preview and POST /api/v1/orders/equity/place

Option Orders¶

Single-LegMulti-Leg

from fidelity_trader.models.single_option_order import SingleOptionOrderRequest

order = SingleOptionOrderRequest(
    acctNum="Z12345678",
    symbol="AAPL250418C00170000",
    orderActionCode="BC",  # BC=Buy Call, SC=Sell Call, BP=Buy Put, SP=Sell Put
    qty=1,
)
preview = client.single_option_orders.preview_order(order)
result = client.single_option_orders.place_order(order, preview.conf_num)

from fidelity_trader.models.option_order import MultiLegOptionOrderRequest

order = MultiLegOptionOrderRequest(...)
preview = client.option_orders.preview_order(order)
result = client.option_orders.place_order(order, preview.conf_num)

Service: POST /api/v1/orders/option/{preview,place} and POST /api/v1/orders/options/{preview,place}

Cancel & Replace (Modify)¶

# Modify an existing order (atomic cancel + new order)
preview = client.cancel_replace.preview_replace(replace_request)
result = client.cancel_replace.place_replace(replace_request, preview.conf_num)

Service: POST /api/v1/orders/replace/{preview,place}

Staged Orders¶

# List staged orders
staged = client.staged_orders.get_staged_orders()
for order in (staged.staged_orders or []):
    print(f"  {order.stage_id}: {order.stage_type}")

# Save a new staged order
result = client.staged_orders.save_staged_order({"symbol": "AAPL", "qty": 10})
print(f"Saved: {result.is_success}")

# Delete a staged order
result = client.staged_orders.delete_staged_order("STG-001")
print(f"Deleted: {result.is_success}")

Response (StagedOrderSaveResponse / StagedOrderDeleteResponse):

result.is_success — True when no ERROR-severity messages

Service: GET /api/v1/orders/staged, POST /api/v1/orders/staged/save, DELETE /api/v1/orders/staged/{stage_id}

Trade Agreement¶

New in v0.3

Accept trade user agreements (e.g., ETF disclosure) required before certain order types.

result = client.trade_agreement.accept_agreement("TRADE-001", "Z12345678")
print(f"Accepted: {result.success}")

Service: POST /api/v1/orders/trade-agreement