Order Statuses & State Machine

Overview

Ordrly uses a structured state machine to manage wholesale order lifecycles. Each order progresses through clearly defined statuses to ensure deterministic financial handling, fulfillment tracking, and auditability.

This document explains how orders transition from creation through payment, invoicing, shipment, returns, and final settlement.

1. Core Order States

Orders may transition through the following high-level states:

• Draft – Order created but not finalized
• Pending Payment – Awaiting card/ACH payment confirmation
• Invoiced – Net Terms invoice created
• Paid – Payment confirmed via Stripe
• Approved – Approved for fulfillment
• Shipped – Fulfillment completed, tracking recorded
• Completed – Order lifecycle complete
• Returned – Return initiated or processed
• Cancelled – Order cancelled prior to fulfillment

2. Payment-Driven Transitions

Immediate Payment (Card/ACH)

• Draft → Pending Payment
• Pending Payment → Paid (via Stripe webhook confirmation)
• Paid → Approved

Net Terms

• Draft → Invoiced
• Invoiced → Approved (fulfillment may proceed based on business rules)
• Invoice Paid → Order marked Paid

Seller payout occurs only after payment confirmation.

3. Fulfillment Transitions

• Approved → Shipped (tracking number recorded)
• Shipped → Completed (after fulfillment finalization)

Shipment events trigger retailer notifications and audit logging.

4. Return & Adjustment Transitions

• Completed → Return Requested
• Return Requested → Approved or Denied
• Approved → Reimbursed
• Reimbursed → Closed

Reimbursements update invoice balances or trigger Stripe refunds depending on payment method.

5. Cancellation Handling

Orders may be cancelled before fulfillment.

• If unpaid, order closes without settlement.
• If paid, refund workflow is triggered.
• If invoiced, AR record is adjusted or voided.

6. Deterministic Financial States

Financial state transitions are driven by:

• Stripe payment confirmations
• Invoice status changes
• Return reimbursements
• Credit adjustments

State transitions are not manual financial overrides. They are event-driven and logged.

7. Audit & Traceability

Each order maintains:

• Status history
• Timestamped transitions
• Linked invoices
• Linked return requests
• Payment reconciliation records

Why This Matters

A structured state machine ensures:

• Deterministic order handling
• Financial clarity
• Controlled payout timing
• Audit-ready operations
• Reduced operational ambiguity

This architecture supports scalable wholesale operations and enterprise-level operational trust.