orcaqubits/medusa-orders

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

| Status | Meaning | |--------|---------| | pending | Order created, awaiting payment | | completed | Payment captured, order confirmed | | archived | Order archived (no further action) | | canceled | Order canceled before fulfillment | | requires_action | Manual intervention needed |

Fulfillment Status

| Status | Meaning | |--------|---------| | not_fulfilled | No items shipped | | partially_fulfilled | Some items shipped | | fulfilled | All items shipped | | shipped / delivered | In transit / arrived | | partially_returned / returned | Items returned |

Payment Status

| Status | Meaning | |--------|---------| | not_paid / awaiting | No payment / pending auth | | authorized | Payment authorized, not captured | | captured | Full payment captured | | partially_refunded / refunded | Refund issued | | canceled | Payment voided |

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

| Operation | Method | Notes | |-----------|--------|-------| | List orders | orderModuleService.listOrders() | Filters, pagination | | Retrieve order | orderModuleService.retrieveOrder() | By ID with relations | | Cancel order | via cancelOrderWorkflow | Workflow-managed | | Archive order | via archiveOrderWorkflow | Workflow-managed | | Complete order | via completeOrderWorkflow | After payment capture |

Fulfillment Workflow

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

| Workflow | Purpose | |----------|---------| | createFulfillmentWorkflow | Create fulfillment for order items | | cancelFulfillmentWorkflow | Cancel a pending fulfillment | | createShipmentWorkflow | Add tracking and mark as shipped | | markOrderFulfillmentAsDeliveredWorkflow | Mark fulfillment as 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

| Workflow | Purpose | |----------|---------| | createReturnWorkflow | Initiate return for order items | | confirmReturnReceiveWorkflow | Mark return items as received | | cancelReturnWorkflow | Cancel a return request |

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

Exchanges and Claims

| Workflow | Purpose | |----------|---------| | createExchangeWorkflow | Initiate exchange (return + new items) | | cancelExchangeWorkflow | Cancel pending exchange | | createClaimWorkflow | Create claim for damaged/wrong items | | cancelClaimWorkflow | Cancel a pending claim |

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

| Action | Description | |--------|-------------| | ITEM_ADD | Add a new line item | | ITEM_REMOVE | Remove an existing line item | | ITEM_UPDATE | Update line item quantity | | SHIPPING_ADD / SHIPPING_REMOVE | Modify shipping methods |

Fetch live docs for orderEditAddItemWorkflow and related edit workflows.

Admin API Routes

| Route Pattern | Method | Purpose | |---------------|--------|---------| | /admin/orders | GET | List orders with filters | | /admin/orders/:id | GET | Retrieve single order | | /admin/orders/:id/cancel | POST | Cancel order | | /admin/orders/:id/fulfillments | POST | Create fulfillment | | /admin/orders/:id/returns | POST | Create return | | /admin/orders/:id/exchanges | POST | Create exchange | | /admin/orders/:id/claims | POST | Create claim |

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.