medusa-workflows

Medusa v2 Workflows

Before writing code

Fetch live docs:

1. Fetch https://docs.medusajs.com/learn/fundamentals/workflows for workflow overview
2. Web-search site:docs.medusajs.com createStep createWorkflow for step and workflow API
3. Web-search site:docs.medusajs.com workflow compensation rollback for compensation patterns
4. Web-search site:docs.medusajs.com workflow hooks for extending built-in workflows
5. Web-search site:docs.medusajs.com built-in workflows list for available core workflows

Workflow Concept

Workflows orchestrate multi-step, transactional operations in Medusa v2:

• Each step is an isolated, retryable unit of work
• Steps can define compensation (rollback) logic for failure recovery
• Workflows execute steps sequentially, in parallel, or conditionally
• Built-in workflows handle core commerce operations (cart, order, fulfillment)
• Custom workflows are invoked from API routes, subscribers, or scheduled jobs

Step Lifecycle

Phase	On Success	On Failure
Step invoked	Execute function	—
Execute function	Proceed to next step	Trigger compensation
All steps done	Workflow complete	—
Compensation	Rollback completed steps in reverse order	Manual resolution

Creating Steps

Step Definition Skeleton

// Fetch live docs for createStep signature
import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"

const myStep = createStep("my-step", async (input, { container }) => {
  const service = container.resolve("my-module")
  const result = await service.createMyEntity(input)
  return new StepResponse(result, result.id) // data, compensationInput
})

Compensation (Rollback)

// Fetch live docs for compensation function signature
const myStep = createStep("my-step",
  async (input, { container }) => {
    return new StepResponse(result, result.id) // forward logic
  },
  async (compensationInput, { container }) => {
    // Rollback logic: undo what forward did
  })