From medusa-commerce
Builds Medusa v2 workflows using createStep for steps with compensation/rollback, parallel execution, hooks for extending built-ins, and when conditions to orchestrate multi-step operations.
How this skill is triggered — by the user, by Claude, or both
Slash command
/medusa-commerce:medusa-workflowsThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Fetch live docs**:
Fetch live docs:
https://docs.medusajs.com/learn/fundamentals/workflows for workflow overviewsite:docs.medusajs.com createStep createWorkflow for step and workflow APIsite:docs.medusajs.com workflow compensation rollback for compensation patternssite:docs.medusajs.com workflow hooks for extending built-in workflowssite:docs.medusajs.com built-in workflows list for available core workflowsWorkflows orchestrate multi-step, transactional operations in Medusa v2:
| 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 |
// 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
})
// 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
})
// Fetch live docs for createWorkflow API
import { createWorkflow, WorkflowResponse }
from "@medusajs/framework/workflows-sdk"
const myWorkflow = createWorkflow("my-workflow", (input) => {
const stepResult = myStep(input)
return new WorkflowResponse(stepResult)
})
| Pattern | API | Purpose |
|---|---|---|
| Sequential | Default step ordering | Steps run one after another |
| Parallel | parallelize(stepA, stepB) | Steps run concurrently |
| Conditional | when(condition, () => step()) | Skip steps based on data |
| Transform | transform(data, fn) | Transform data between steps |
// Fetch live docs for parallelize import
import { parallelize } from "@medusajs/framework/workflows-sdk"
const [resultA, resultB] = parallelize(stepA(input), stepB(input))
// Fetch live docs for when() API
import { when } from "@medusajs/framework/workflows-sdk"
when(input, (data) => data.sendEmail === true, () => {
return sendEmailStep(input)
})
| Context | Invocation Pattern |
|---|---|
| API Route | await myWorkflow(req.scope).run({ input }) |
| Subscriber | await myWorkflow(container).run({ input }) |
| Scheduled Job | await myWorkflow(container).run({ input }) |
| Another Workflow | Use as a step with createStep wrapping |
Hooks allow extending built-in workflows without modifying core code:
| Hook Type | Purpose |
|---|---|
before | Run custom logic before a built-in step |
after | Run custom logic after a built-in step |
// src/workflows/hooks/my-hook.ts
// Fetch live docs for hook registration API
import { createProductsWorkflow } from "@medusajs/medusa/core-flows"
createProductsWorkflow.hooks.productsCreated(
async ({ products, additional_data }, { container }) => {})
// Fetch live docs for available hook names per workflow
| Workflow | Domain | Key Hooks |
|---|---|---|
createProductsWorkflow | Catalog | productsCreated |
updateProductsWorkflow | Catalog | productsUpdated |
createCartWorkflow | Cart | cartCreated |
completeCartWorkflow | Checkout | cartCompleted |
createOrderWorkflow | Orders | orderCreated |
createFulfillmentWorkflow | Fulfillment | fulfillmentCreated |
createPaymentCollectionWorkflow | Payments | hook available |
createCustomerAccountWorkflow | Customers | hook available |
Fetch live docs for the complete list -- new workflows and hooks are added in each Medusa release.
| Scenario | Compensation Action |
|---|---|
| Record created | Delete the created record |
| Payment captured | Refund the payment |
| Inventory reserved | Release the reservation |
| Email sent | Log warning (cannot unsend) |
| External API called | Call reverse/cancel endpoint |
Key rules:
StepResponseparallelize for independent steps to improve performancewhen for conditional logic -- do not put branching inside stepsreserve-inventory-step)transform for data reshaping -- do not create steps that only transform dataFetch the Medusa workflow documentation for exact createStep/createWorkflow signatures, hook names, and built-in workflow list before implementing.
npx claudepluginhub orcaqubits/agentic-commerce-skills-plugins --plugin medusa-commerceGuides Medusa backend development for custom modules, API routes, workflows, data models, module links, and business logic with architecture patterns, best practices, and rules.
Implements Medusa v2 event subscribers for pub/sub handling, handler functions, cron scheduled jobs, and Redis/in-memory event bus. Use when reacting to commerce events like product.created or order.placed.
Guides developers step-by-step through building a custom brands feature in Medusa, teaching modules, workflows, API routes, module links, hooks, and admin UI customization.