Order Management System Design

Order Lifecycle

Order States:
├── new (pending payment)
├── pending_payment (waiting for payment)
├── processing (payment received, fulfillment started)
├── complete (shipped/delivered)
├── closed (post-delivery period ended)
├── canceled (canceled by customer/admin)
├── holded (admin hold)
└── review (fraud review)

Order Statuses:
├── pending
├── processing
│   ├── shipped
│   ├── delivered
│   └── canceled
├── complete
└── closed

Order Data Model

-- Order table
CREATE TABLE sales_order (
    entity_id INT AUTO_INCREMENT PRIMARY KEY,
    increment_id VARCHAR(50) UNIQUE,
    store_id INT,
    customer_id INT,
    customer_email VARCHAR(255),
    customer_firstname VARCHAR(255),
    customer_lastname VARCHAR(255),
    status VARCHAR(32),
    state VARCHAR(32),
    subtotal DECIMAL(12,4),
    discount_amount DECIMAL(12,4),
    shipping_amount DECIMAL(12,4),
    tax_amount DECIMAL(12,4),
    grand_total DECIMAL(12,4),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- Order item table
CREATE TABLE sales_order_item (
    item_id INT AUTO_INCREMENT PRIMARY KEY,
    order_id INT,
    parent_item_id INT NULL,
    product_id INT,
    sku VARCHAR(255),
    name VARCHAR(255),
    qty_ordered DECIMAL(12,4),
    qty_shipped DECIMAL(12,4) DEFAULT 0,
    qty_canceled DECIMAL(12,4) DEFAULT 0,
    qty_refunded DECIMAL(12,4) DEFAULT 0,
    price DECIMAL(12,4),
    discount_amount DECIMAL(12,4),
    row_total DECIMAL(12,4)
);

-- Order status history
CREATE TABLE sales_order_status_history (
    entity_id INT AUTO_INCREMENT PRIMARY KEY,
    order_id INT,
    comment TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    customer_notified TINYINT(1) DEFAULT 0,
    status VARCHAR(32)
);

State Transitions

// Order state machine
$transitions = [
    'new' => ['pending_payment', 'processing', 'canceled'],
    'pending_payment' => ['processing', 'canceled'],
    'processing' => ['complete', 'canceled', 'holded'],
    'complete' => ['closed'],
    'holded' => ['processing', 'canceled'],
    'review' => ['processing', 'canceled'],
];

// State transition validation
public function canTransition($from, $to)
{
    $allowed = $transitions[$from] ?? [];
    return in_array($to, $allowed);
}

// Update order state
public function setState($order, $newState, $comment = '')
{
    if (!$this->canTransition($order->getState(), $newState)) {
        throw new \Exception('Invalid state transition');
    }
    
    $order->setState($newState);
    $order->setStatus($newState);
    
    if ($comment) {
        $order->addStatusHistoryComment($comment);
    }
    
    $order->save();
    
    // Trigger state change event
    $this->eventManager->dispatch('sales_order_state_change', [
        'order' => $order,
        'old_state' => $oldState,
        'new_state' => $newState
    ]);
}

Order Processing

// Process order after payment
public function processOrder($order)
{
    // 1. Update order status to processing
    $this->setState($order, 'processing', 'Payment received');
    
    // 2. Create invoice (if auto-invoice enabled)
    if ($this->config->isAutoInvoice()) {
        $this->invoiceService->create($order);
    }
    
    // 3. Notify warehouse
    $this->warehouseService->notifyNewOrder($order);
    
    // 4. Send order confirmation email
    $this->emailService->sendOrderConfirmation($order);
    
    // 5. Update inventory
    $this->inventoryService->deductStock($order);
}

Order Completion

// Complete order after delivery
public function completeOrder($order)
{
    // 1. Verify all items shipped
    $allShipped = true;
    foreach ($order->getItems() as $item) {
        if ($item->getQtyShipped() < $item->getQtyOrdered()) {
            $allShipped = false;
            break;
        }
    }
    
    if (!$allShipped) {
        throw new \Exception('Not all items shipped');
    }
    
    // 2. Update order status
    $this->setState($order, 'complete', 'Order delivered');
    
    // 3. Send thank you email
    $this->emailService->sendThankYou($order);
    
    // 4. Update customer lifetime value
    $this->customerService->updateLtv($order);
    
    // 5. Request review
    $this->reviewService->requestReview($order);
}

Fulfillment Workflow

1. Order received
   ├── Validate order data
   ├── Check inventory availability
   └── Assign to fulfillment center

2. Pick and pack
   ├── Generate pick list
   ├── Pick items from warehouse
   ├── Pack items
   └── Print shipping label

3. Ship
   ├── Hand to carrier
   ├── Update tracking info
   ├── Send shipping notification
   └── Update order status

4. Deliver
   ├── Track shipment
   ├── Confirm delivery
   └── Complete order

Shipment Management

// Create shipment
public function createShipment($order, $items, $trackNumber)
{
    $shipment = $this->shipmentFactory->create();
    $shipment->setOrder($order);
    
    // Add items
    foreach ($items as $item) {
        $shipmentItem = $this->shipmentItemFactory->create();
        $shipmentItem->setOrderItem($item->getOrderItem());
        $shipmentItem->setQty($item->getQty());
        $shipment->addItem($shipmentItem);
    }
    
    // Add tracking
    $track = $this->trackFactory->create();
    $track->setNumber($trackNumber);
    $track->setCarrierCode('custom');
    $track->setTitle('Custom Carrier');
    $shipment->addTrack($track);
    
    // Save shipment
    $shipment->save();
    
    // Send shipping notification
    $this->emailService->sendShippingNotification($order, $shipment);
    
    return $shipment;
}

// Partial shipment
public function createPartialShipment($order, $items)
{
    // Create shipment for available items
    $shipment = $this->createShipment($order, $items);
    
    // Update order status
    $shippedCount = $this->getTotalShippedCount($order);
    $orderedCount = $this->getTotalOrderedCount($order);
    
    if ($shippedCount < $orderedCount) {
        $order->setState('processing', 'Partial shipment created');
    }
    
    return $shipment;
}

Return Process

1. Return request
   ├── Customer submits return
   ├── Admin reviews request
   └── Approve/reject

2. Return received
   ├── Receive returned items
   ├── Inspect items
   └── Update return status

3. Refund processing
   ├── Calculate refund amount
   ├── Process refund
   ├── Update order status
   └── Send refund confirmation

Return Management

// Create return
class ReturnService
{
    public function createReturn($orderId, $items, $reason)
    {
        $order = $this->orderRepository->get($orderId);
        
        $return = $this->returnFactory->create();
        $return->setOrderId($orderId);
        $return->setStatus('pending');
        $return->setReason($reason);
        
        foreach ($items as $item) {
            $returnItem = $this->returnItemFactory->create();
            $returnItem->setOrderItemId($item['item_id']);
            $returnItem->setQty($item['qty']);
            $returnItem->setReason($item['reason']);
            $return->addItem($returnItem);
        }
        
        $return->save();
        
        // Notify admin
        $this->emailService->sendReturnRequest($return);
        
        return $return;
    }
    
    public function processRefund($returnId)
    {
        $return = $this->returnRepository->get($returnId);
        $order = $return->getOrder();
        
        // Calculate refund amount
        $refundAmount = $this->calculateRefundAmount($return);
        
        // Process refund through payment gateway
        $refund = $this->paymentService->refund($order, $refundAmount);
        
        // Update order status
        $order->addStatusHistoryComment(
            'Refund processed: ' . $refundAmount
        );
        $order->save();
        
        // Update return status
        $return->setStatus('refunded');
        $return->setRefundId($refund->getId());
        $return->save();
        
        // Send refund confirmation
        $this->emailService->sendRefundConfirmation($return);
        
        return $refund;
    }
}

Refund Calculation

// Calculate refund amount
public function calculateRefundAmount($return)
{
    $order = $return->getOrder();
    $refundAmount = 0;
    
    foreach ($return->getItems() as $returnItem) {
        $orderItem = $returnItem->getOrderItem();
        
        // Product price refund
        $itemRefund = $orderItem->getPrice() * $returnItem->getQty();
        
        // Discount proportional refund
        if ($orderItem->getDiscountAmount() > 0) {
            $discountRefund = ($orderItem->getDiscountAmount() / $orderItem->getQtyOrdered()) * $returnItem->getQty();
            $itemRefund -= $discountRefund;
        }
        
        $refundAmount += $itemRefund;
    }
    
    // Shipping refund (optional)
    if ($this->shouldRefundShipping($return)) {
        $refundAmount += $order->getShippingAmount();
    }
    
    // Tax refund
    $taxRefund = $this->calculateTaxRefund($return);
    $refundAmount += $taxRefund;
    
    return $refundAmount;
}