order-lifecycle

What this skill does

# Order Lifecycle

## Purpose
Guide the design and implementation of order lifecycle management in trading systems. Covers order states and transitions, FIX protocol message flows, order types and time-in-force instructions, cancel/replace workflows, order validation, and state machine design. Enables building or evaluating order management systems that correctly handle the full lifecycle from order creation through fill, cancellation, or expiration.

## Layer
11 — Trading Operations (Order Lifecycle & Execution)

## Direction
both

## When to Use
- Designing or implementing an order state machine for an order management system (OMS) or execution management system (EMS)
- Building or debugging FIX protocol connectivity to exchanges, ECNs, or execution venues
- Implementing cancel/replace workflows and handling race conditions between cancel requests and fills
- Defining order validation rules for pre-submission checks (buying power, position limits, restricted lists, symbol validity)
- Evaluating order types and time-in-force instructions for different trading strategies and market conditions
- Designing multi-leg or contingent order structures (OCO, bracket, conditional orders)
- Building order audit trail systems that satisfy CAT reporting and regulatory reconstruction requirements
- Troubleshooting order rejections, unexpected state transitions, or lost order scenarios
- Reviewing or hardening an existing OMS against edge cases in order state management
- Implementing order persistence and recovery mechanisms for system restarts or failover scenarios

## 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 -> Canceled (venue canceled instead of replacing, sometimes due to insufficient quantity after a fill)
- Suspended -> Accepted (halt lifted, order reactivated)
- Suspended -> Expired (order expires during halt)
- Done for Day -> Accepted (next trading day, order reactivated)
- Done for Day -> Expired (GTC expiration reached)

**State persistence and recovery:** The order state must be persisted durably — typically to a database or write-ahead log — before any acknowledgment is sent to the order originator or any action is taken on the order. If the OMS restarts after a crash, it must be able to reconstruct the current state of every active order from persisted state plus any messages received from execution venues during recovery. This requires idempotent message processing (handling duplicate execution reports without double-counting fills) and state reconciliation with venue order status queries.

### Order Types
Order types define the execution instructions that govern how an order interacts with the market.

- **Market order:** Execute immediately at the best available price. Guarantees execution (in liquid markets) but not price. Appropriate for urgent execution needs. Risk: slippage in volatile or illiquid markets; the execution price may differ substantially from the last quoted price.
- **Limit order:** Execute at the specifie