medusa-orders

name	medusa-orders
description	Manage Medusa v2 orders — order lifecycle and state machine, fulfillment workflows, returns, exchanges, claims, draft orders, and order editing. Use when working with order processing.

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.