From medusa-commerce
Manages Medusa v2 orders: lifecycle and state machine, fulfillment workflows, returns, exchanges, claims, draft orders, and editing. Use for order processing tasks.
npx claudepluginhub orcaqubits/agentic-commerce-skills-plugins --plugin medusa-commerceThis skill is limited to using the following tools:
**Fetch live docs**:
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Fetch live docs:
site:docs.medusajs.com order module for order data model and service methodssite:docs.medusajs.com order workflow fulfillment for fulfillment workflow stepssite:docs.medusajs.com return exchange claim for return/exchange/claim flowshttps://docs.medusajs.com/resources/references/order and review the IOrderModuleService interfacemedusajs v2 draft order editing 2026 for latest order editing workflowsPENDING ──> COMPLETED ──> FULFILLED ──> DELIVERED
│ │ │
└─ CANCELED └─ RETURNED └─ PARTIALLY_RETURNED
| 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 |
| 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 |
| 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 ──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.
| 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 |
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.
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).
| 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.
// 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
Modify orders after creation using the Order Change mechanism:
Begin Edit ──> Add/Remove Items ──> Confirm Edit ──> Payment Adjustment
| 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
orderEditAddItemWorkflowand related edit workflows.
| 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.
createShipmentWorkflow to attach tracking info (not direct service calls)order.placed, order.completed, order.canceled) for side effectsFetch the Medusa v2 order module documentation and workflow references for exact service method signatures, workflow inputs, and state machine transitions before implementing.