Medusa v2 Order Management

Before writing code

Fetch live docs:

1. Web-search site:docs.medusajs.com order module for order data model and service methods
2. Web-search site:docs.medusajs.com order workflow fulfillment for fulfillment workflow steps
3. Web-search site:docs.medusajs.com return exchange claim for return/exchange/claim flows
4. Fetch https://docs.medusajs.com/resources/references/order and review the IOrderModuleService interface
5. Web-search medusajs v2 draft order editing 2026 for latest order editing workflows

Order Lifecycle

State Machine

PENDING ──> COMPLETED ──> FULFILLED ──> DELIVERED
    │           │              │
    └─ CANCELED └─ RETURNED    └─ PARTIALLY_RETURNED

Order Statuses

Fulfillment Status

Payment Status

Order Module Architecture

Order Module ──link──> Payment Module (payment collections)
Order Module ──link──> Fulfillment Module (fulfillments)
Order Module ──link──> Product Module (line items)
Order Module ──link──> Customer Module (customer)

Fetch live docs for exact link definitions and remote query patterns for cross-module order data.

Key Service Methods

Fulfillment Workflow

Order Confirmed ──> Create Fulfillment ──> Create Shipment ──> Delivered

Fetch live docs for workflow input shapes -- fulfillment items, tracking numbers, and labels.

Returns

Return Requested ──> Return Received ──> Refund Issued
       └─> Return Canceled      └─> Items Restocked

Return reasons are configurable via the Return Reason entity (supports nesting via parent_return_reason_id).

Exchanges and Claims

Exchanges combine return of original items with shipment of replacements, handling price differences automatically. Claims can result in refund, replacement, or both.

Draft Orders

// Skeleton: create draft order
// Fetch live docs for createOrderWorkflow input shape
import { createOrderWorkflow } from "@medusajs/medusa/core-flows"

const { result } = await createOrderWorkflow(container)
  .run({ input: { /* order data */ } })
// Fetch live docs for CreateOrderWorkflowInput

Order Editing

Modify orders after creation using the Order Change mechanism:

Begin Edit ──> Add/Remove Items ──> Confirm Edit ──> Payment Adjustment

Order Change Actions

Fetch live docs for orderEditAddItemWorkflow and related edit workflows.

Admin API Routes

Fetch live docs for request body shapes and query parameters on each route.

Best Practices

Order Processing

• Always use workflows for order mutations -- they handle cross-module orchestration
• Check payment status before creating fulfillments
• Use order changes for post-creation modifications -- never mutate order data directly
• Implement idempotency keys for order creation to prevent duplicates

Fulfillment

• Support partial fulfillments -- one order may ship from multiple locations
• Track fulfillment status through the state machine, not manual status sets
• Use createShipmentWorkflow to attach tracking info (not direct service calls)

Returns and Exchanges

• Configure return reasons as a hierarchy (parent + child reasons) for analytics
• Exchanges automatically calculate price differences -- do not manually compute
• Claims should reference the original fulfillment for traceability

Observability

• Subscribe to order events (order.placed, order.completed, order.canceled) for side effects
• Use subscribers for notifications, analytics, and third-party integrations

Fetch the Medusa v2 order module documentation and workflow references for exact service method signatures, workflow inputs, and state machine transitions before implementing.