Order object, placement, modification, and cancellation

Minimal placement

from ib_async import LimitOrder, Stock

contract = Stock("AAPL", "SMART", "USD", primaryExchange="NASDAQ")
[contract] = await ib.qualifyContractsAsync(contract)

order = LimitOrder(
    action="BUY",
    totalQuantity=10,
    lmtPrice=180.00,
    account="DU1234567",
    tif="DAY",
    orderRef="strategy:rebalance:2026-07-14",
)
trade = ib.placeOrder(contract, order)

placeOrder allocates an order ID for a new order, sends it, creates or updates a Trade, and returns immediately. The return is not acceptance. Observe trade.statusEvent, trade.fillEvent, trade.commissionReportEvent, trade.cancelledEvent, or the matching IB events.

Required and overloaded fields

The practical minimum is action, totalQuantity (or supported cashQty), and orderType, plus the price/trigger fields required by that type. lmtPrice and auxPrice are deliberately overloaded by IBKR:

Type	lmtPrice	auxPrice	Other key fields
LMT	limit	unset	—
STP	unset	stop trigger	triggerMethod optionally
STP LMT	limit after trigger	stop trigger	—
TRAIL	normally unset	absolute trail amount	use either auxPrice or trailingPercent; optional trailStopPrice
TRAIL LIMIT	do not confuse with offset	absolute trail amount	lmtPriceOffset, optional trailStopPrice; unset unused competing fields
REL	price cap	offset	routing/product dependent
PEG MID	limit cap	midpoint offset	sign/direction rules apply
VOL	limit premium	optional	volatility and delta-neutral fields drive the order

UNSET_DOUBLE/UNSET_INTEGER are protocol sentinels. Zero is a real value for many fields and is not always equivalent to unset. Convenience constructors set the right order type but do not validate exchange support, ticks, permissions, or economic sense.

Time in force

TIF	Behavior and caveats
DAY	Valid for the current trading day/session; default behavior when omitted is server/UI dependent.
GTC	Works until fill/cancel but IBKR can auto-cancel on corporate actions, account/session policy, or long inactivity; never treat as immortal.
IOC	Execute immediately to the extent possible; cancel remainder.
GTD	Active until goodTillDate; specify a valid timezone.
OPG	Opening auction; combine with MKT for MOO or LMT for LOO.
FOK	Fill entire quantity immediately or cancel, where supported.
DTC	Day-until-cancel behavior for supported products/venues.
AUC	Auction routing behavior used by supported auction orders.

Time strings should use explicit time zones. Modern TWS API accepts UTC yyyyMMdd-HH:mm:ss and local/exchange formats with a timezone. Ambiguous local times around DST can be rejected or interpreted unexpectedly.

Routing and execution controls

• outsideRth is valid only where the contract/order/venue supports it; error 411 means it is not.
• hidden, displaySize, allOrNone, minQty, blockOrder, sweepToFill, and notHeld are venue/product-specific.
• triggerMethod chooses how simulated stops/conditions are triggered; the default depends on security type. Bid/ask, last, double-last, midpoint, and other methods have different manipulation and liquidity implications.
• overridePercentageConstraints=True bypasses configured precautionary percentage checks. Use only with independent price validation.
• usePriceMgmtAlgo opts into IBKR price management where supported.
• orderRef is application metadata. Make it stable and searchable, but do not assume uniqueness is enforced.
• account should be explicit in multi-account sessions.

Every field is listed in Order, including scale, hedge, delta-neutral, MiFID II, advisor allocation, ATS, and advanced-error fields.

What-if

state = await ib.whatIfOrderAsync(contract, order)
print(state.initMarginChange, state.maintMarginChange, state.commission)

A what-if asks for estimated margin/commission. It does not reserve buying power, guarantee acceptance, or capture price movement between check and placement. Some combos/order types do not support it.

Modify

Modify an active API order by changing permitted fields on the same Order and calling placeOrder again with its existing orderId:

trade.order.lmtPrice = 179.50
ib.placeOrder(trade.contract, trade.order)

Only the owning client can normally modify the order. Changing identity-defining fields can be interpreted as an invalid modification (error 105). Modification can affect exchange queue priority. Never synthesize an order ID from stale storage without first reconciling the live order and permanent ID.

Cancel

ib.cancelOrder(trade.order)

The local status can become PendingCancel immediately; wait for Cancelled, ApiCancelled, a fill, or a definitive error. A cancel races with execution. reqGlobalCancel() cancels all open orders accessible to the session, including orders submitted manually or by other clients; treat it as an emergency operation.

Statuses and duplicate callbacks

Common statuses are PendingSubmit, ApiPending, PreSubmitted, Submitted, PendingCancel, ApiCancelled, Cancelled, Filled, and Inactive. PreSubmitted often means a simulated order is held by IBKR. Inactive requires examining errors/order state. A market order can fill before an intermediate status callback arrives, and duplicate orderStatus callbacks are normal. Fills are the authoritative evidence of execution.

See Order statuses and lifecycle semantics for the complete current IBKR Campus status table, additional official API-side statuses, callback fields, transition caveats, and ib_async helper classifications.

Official references: order class, placing orders, and message codes.