Order Lifecycle

Orders are the heart of the marketplace. Each order represents items from a single seller that need to be shipped to a buyer. When someone buys from multiple sellers in one checkout, we create multiple orders — one per seller — all linked to the same transaction.

Understanding the order lifecycle is essential for debugging issues, building new features, or just knowing what’s happening behind the scenes when a user says “my order is stuck.”

The State Machine

Orders move through a series of statuses, from creation to completion (or cancellation). Here’s the full picture — it might look complex at first, but we’ll break it down piece by piece.

Understanding Status Categories

Not all statuses are created equal. Some are “in progress” waiting for someone to take action, while others are final states where the order is done and no more changes can happen.

Common Flows

Most orders follow one of a few common paths. Let’s walk through each one.

The Happy Path: Successful Delivery

This is what we hope happens with every order:

Cancellation Flow

Sometimes buyers change their mind or sellers can’t fulfill an order. Here’s how cancellations work:

Key Cancellation Rules

Delivery and the 7-Day Hold

After an order is delivered, we don’t immediately release funds to the seller. There’s a 7-day hold period that gives buyers time to:

• Inspect the items they received
• Make sure everything matches the listing
• Open a dispute if something is wrong

The Order Data Model

When you’re debugging or building features, you’ll work with the Order document. Here are the key fields:

Status History: The Audit Trail

Every time an order’s status changes, we record it. This creates a complete history that’s invaluable for customer support and debugging.

interface OrderStatusChange {
  from: OrderStatus      // Previous status
  to: OrderStatus        // New status
  at: Date              // When it changed
  actor: 'buyer' | 'seller' | 'system' | 'admin'
  reason?: string       // Why (for cancellations, etc.)
  metadata?: Record<string, unknown>
}

Domain Service: Business Rules

The OrderDomainService contains pure functions that encode all the business rules. These are the source of truth for “can this action happen?”

Background Automation

Several order lifecycle events happen automatically via a cron-triggered background job (process-order-lifecycle) that runs every 30 minutes. The job queries for orders matching specific criteria and processes them through the state machine.

The handler follows a “query batch, process each, continue on error” pattern — if one order fails, the rest still get processed. Individual errors are logged and the job reports a summary at the end.

Code Locations