/order-lifecycle

name: order-lifecycle
description: "Guide the design and implementation of order lifecycle management in trading systems. Owns FIX application-layer message flows (NewOrderSingle, ExecutionReport, cancel/replace) and order state. Use when building an order state machine for an OMS or EMS, handling cancel/replace race conditions, defining pre-submission validation rules (buying power, position limits, restricted lists), selecting order types and time-in-force instructions, designing multi-leg or OCO or bracket orders, building CAT-compliant audit trails, troubleshooting order rejections or unexpected state transitions, hardening an OMS against edge cases, or implementing order persistence and recovery for failover. Also covers execution-report handling, ClOrdID chaining, and partial fill aggregation. For FIX session management (logon, sequence gaps, disconnects) see exchange-connectivity."

Order Lifecycle

Core Concepts

Order State Machine

The order state machine is the central abstraction in any order management system. It defines every state an order can occupy and every valid transition between states. A correctly implemented state machine prevents impossible transitions (such as filling a canceled order), ensures audit trail completeness, and provides the foundation for order status reporting to clients, counterparties, and regulators.

**Canonical order states:**

• **New:** The order has been created internally but not yet transmitted to an execution venue. This is the initial state in the OMS after order entry and validation.
• **Pending New:** The order has been transmitted to the execution venue but no acknowledgment has been received. The order is in flight. This state exists because network latency and venue processing time create a window between submission and acceptance.
• **Accepted (New on venue):** The execution venue has acknowledged receipt of the order and placed it on the order book. The FIX ExecType=New / OrdStatus=New acknowledgment has been received.
• **Partially Filled:** The order has received one or more executions but the full quantity has not yet been filled. The cumulative filled quantity is greater than zero but less than the order quantity.
• **Filled:** The order has been completely executed. The cumulative filled quantity equals the order quantity. This is a terminal state.
• **Pending Cancel:** A cancel request has been submitted for the order but the venue has not yet confirmed the cancellation. The original order may still receive fills during this window — this is a critical race condition.
• **Canceled:** The order has been successfully canceled by the venue. Any unfilled quantity is no longer eligible for execution. This is a terminal state. If partial fills occurred before cancellation, the order is sometimes described as "partially filled and canceled" — the fills stand and the remaining quantity is canceled.
• **Pending Replace:** A cancel/replace (amend) request has been submitted but not yet confirmed. As with Pending Cancel, fills may still arrive during this window.
• **Replaced:** The original order has been replaced by a new order with amended parameters (price, quantity, or other fields). The original order transitions to Replaced (terminal), and a new order is created with the amended terms. In FIX, replacement creates a chain linked by ClOrdID and OrigClOrdID.
• **Rejected:** The execution venue has rejected the order. Common rejection reasons include invalid symbol, invalid order type for the venue, price outside acceptable range, insufficient permissions, or market closed. This is a terminal state.
• **Expired:** The order's time-in-force instruction caused it to expire without being fully filled. A DAY order expires at market close; a GTD order expires on its specified date. This is a terminal state.
• **Suspended:** The order has been temporarily suspended by the venue, typically due to a trading halt on the security, a circuit breaker activation, or a regulatory halt. The order remains on the book but is not eligible for matching until the suspension is lifted.
• **Done for Day:** The order is not eligible for further execution on the current trading day but may resume on the next trading day. This applies to multi-day orders (GTC) that have not yet been fully filled.

**Terminal vs. non-terminal states:** Terminal states (Filled, Canceled, Replaced, Rejected, Expired) represent the end of an order's lifecycle — no further transitions are possible. Non-terminal states (New, Pending New, Accepted, Partially Filled, Pending Cancel, Pending Replace, Suspended, Done for Day) may transition to other states. The state machine must enforce the invariant that no transition out of a terminal state is ever permitted.

**Valid state transitions (representative, not exhaustive):**

• New -> Pending New (order submitted to venue)
• Pending New -> Accepted (venue acknowledges)
• Pending New -> Rejected (venue rejects)
• Accepted -> Partially Filled (first partial execution)
• Accepted -> Filled (single complete execution)
• Accepted -> Pending Cancel (cancel request sent)
• Accepted -> Pending Replace (replace request sent)
• Accepted -> Expired (time-in-force expiration)
• Accepted -> Suspended (trading halt)
• Partially Filled -> Partially Filled (additional partial execution)
• Partially Filled -> Filled (final execution completes order)
• Partially Filled -> Pending Cancel (cancel remaining quantity)
• Partially Filled -> Pending Replace (amend remaining quantity or price)
• Pending Cancel -> Canceled (cancel confirmed)
• Pending Cancel -> Filled (fill arrived before cancel was processed — race condition)
• Pending Cancel -> Partially Filled (partial fill during cancel processing)
• Pending Replace -> Replaced (replace confirmed, new order created)
• Pending Replace -> Filled (fill arrived before replace was processed)
• Pending Replace -> Partially Filled (partial fill during replace processing)
• Pending Replace -> Cance