How to Create a Workflow

A workflow is the orchestration layer. It coordinates a business operation across one or more modules as a series of steps, with automatic rollback (compensation) when any step fails. Every mutation in Mercur runs inside a workflow. This is the single most important rule in the architecture.

All mutations go through a workflow. API routes, subscribers, and scheduled jobs never write to the database directly. They run a workflow. That is what gives every mutation validation, event emission, and rollback.

Workflows are a Medusa framework primitive. This page focuses on the constraints and conventions that trip people, and agents, up.

The composition function is not normal JavaScript

The function you pass to createWorkflow is a composition function. It runs once at build time to wire steps together. It does not execute your business logic at request time. Because of that, it has hard constraints.

Inside a createWorkflow composition function you must not:

use async / await
use arrow functions for the composition body (use a named function)
use if / else, for, while, or try/catch
use new Date(), Math.random(), or any non-deterministic call
access properties of a step’s output directly (e.g. result.id)

These run at composition time, not execution time, so they either do nothing useful or break replay and rollback.

Anything that looks like normal logic goes into a step (for side effects) or a transform (for shaping data between steps):

src/workflows/create-brands.ts

import {
  createWorkflow,
  transform,
  WorkflowResponse,
} from "@medusajs/framework/workflows-sdk"

import { createBrandsStep } from "./steps"

export const createBrandsWorkflow = createWorkflow(
  "create-brands",
  function (input: CreateBrandsWorkflowInput) {
    // ✅ shape data with transform, not inline expressions
    const toCreate = transform(input, ({ brands }) =>
      brands.map((b) => ({ ...b, is_active: b.is_active ?? true }))
    )

    const brands = createBrandsStep(toCreate)

    return new WorkflowResponse(brands)
  }
)

Need a conditional or a computed value? Use transform to derive data, when to run a step conditionally, and put date, random, or id generation inside a step. Never branch in the composition body itself.

One mutation per step and compensation

A step is the unit of work and the unit of rollback. The rule: each step performs a single mutation and defines how to undo it. createStep takes an invoke function and a compensation function. The invoke returns a StepResponse whose second argument is the data the compensation needs.

src/workflows/steps/create-brands.ts

import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
import BrandModuleService from "../../modules/brand/service"
import { BRAND_MODULE } from "../../modules/brand"

export const createBrandsStep = createStep(
  "create-brands",
  async (data: CreateBrandInput[], { container }) => {
    const service = container.resolve<BrandModuleService>(BRAND_MODULE)
    const brands = await service.createBrands(data)
    // 2nd arg → passed to the compensation function below
    return new StepResponse(brands, brands.map((b) => b.id))
  },
  async (ids: string[] | undefined, { container }) => {
    if (!ids?.length) {
      return
    }
    const service = container.resolve<BrandModuleService>(BRAND_MODULE)
    await service.deleteBrands(ids)
  }
)

When a later step in the workflow throws, Medusa runs the compensation functions of the already-completed steps in reverse. The createBrands above is undone by deleteBrands. Splitting mutations one per step is what makes this reliable: a step that does two writes can only half-compensate.

Reuse built-in steps

Don’t hand-roll what the framework already ships. Medusa’s core-flows exports composable steps you should reuse instead of writing your own:

Need	Built-in step
Create/remove module links	`createRemoteLinkStep` / `dismissRemoteLinkStep`
Emit a domain event	`emitEventStep`
Call another workflow as a step	`otherWorkflow.runAsStep({ input })`

import { emitEventStep } from "@medusajs/medusa/core-flows"

export const createBrandsWorkflow = createWorkflow(
  "create-brands",
  function (input: CreateBrandsWorkflowInput) {
    const brands = createBrandsStep(input.brands)

    // reuse a whole workflow as one step
    notifyOwnersWorkflow.runAsStep({ input: { brands } })

    // reuse the built-in event step
    emitEventStep({ eventName: "brand.created", data: { ids: brands } })

    return new WorkflowResponse(brands)
  }
)

Prefer runAsStep over duplicating logic. When two workflows need the same sequence, extract it into its own workflow and call it as a step from both. You get one place to maintain, and correct compensation for free.

Hooks let others extend your workflow

Expose extension points with createHook so consumers can inject behaviour such as validation or side effects without forking the workflow. Add a validate hook before the mutation and a brandsCreated hook after it:

const validate = createHook("validate", { input })

const brands = createBrandsStep(input.brands)

const brandsCreated = createHook("brandsCreated", {
  brands,
  additional_data: input.additional_data,
})

return new WorkflowResponse(brands, {
  hooks: [validate, brandsCreated],
})

Consumers register a handler on the hook to run custom logic at that point. This is the sanctioned way to extend a workflow. See Extend a workflow.

The query engine

Reads inside a step, and anywhere else, go through Query, the graph engine that resolves data across modules and links. Resolve it from the container and call query.graph:

import { ContainerRegistrationKeys } from "@medusajs/framework/utils"

const query = container.resolve(ContainerRegistrationKeys.QUERY)

const { data: brands } = await query.graph({
  entity: "brand",
  fields: ["id", "name", "products.*"], // follows the product ↔ brand link
  filters: { is_active: true },
})

Query is for reads. Never try to mutate through it, and never resolve another module’s service inside a step to read its data. Go through Query so module isolation and links are respected.

Checklist for a workflow

Composition function is a named function, with no async/await, if, loops, try/catch, new Date(), or step-output property access.
Data shaping between steps uses transform; conditional steps use when.
Each step does exactly one mutation and defines a compensation function.
StepResponse passes the compensation the data it needs to undo the work.
Built-in steps (createRemoteLinkStep, emitEventStep) and runAsStep are reused instead of reimplemented.
Reads use query.graph; no cross-module service calls.
Extension points are exposed as hooks, not by forking.

Next steps

Extend a workflow

Best practices overview

See how workflows fit the wider Mercur architecture.

How-Tos

Integrations

Deployment

The composition function is not normal JavaScript

One mutation per step and compensation

Reuse built-in steps

Hooks let others extend your workflow

The query engine

Checklist for a workflow

Next steps

Extend a workflow

Best practices overview

​The composition function is not normal JavaScript

​One mutation per step and compensation

​Reuse built-in steps

​Hooks let others extend your workflow

​The query engine

​Checklist for a workflow

​Next steps

Extend a workflow

Best practices overview

The composition function is not normal JavaScript

One mutation per step and compensation

Reuse built-in steps

Hooks let others extend your workflow

The query engine

Checklist for a workflow

Next steps